Neb Standards Frontend

Keyboard and Screen Reader

• All interactive elements must be keyboard-accessible
• Visible focus indicators on all focusable elements
• High contrast mode support
• Test with screen readers before release
• Aim for 8th-grade reading level in content

Forms

• Clear labels and placeholder text on all form fields
• Real-time validation with helpful error messages
• Proper error states with accessible announcements

Testing

• Use axe for automated accessibility testing
• Lighthouse accessibility audits as part of CI

Core Web Vitals

Performance targets enforced across all web properties:

Optimization Checklist

• Critical CSS inlined; non-critical CSS loaded asynchronously
• Images: WebP format preferred, lazy loading for non-critical content, proper sizing
• Code splitting and bundle optimization (tree-shaking, dynamic imports)
• Font loading optimized (preload, font-display: swap)
• CDN delivery for all static assets
• Skeleton screens for loading states to avoid layout shifts
• ESLint + Prettier for code quality; Lighthouse for auditing

CSS & Responsive Design

Modern CSS

• CSS Grid and Flexbox for layouts
• CSS custom properties (variables) for theming
• BEM methodology for class naming
• Mobile-first responsive design (required)

Breakpoints

SCSS Best Practices

• Max 3 levels of nesting
• Variables for colors, spacing, breakpoints
• Mixins for reusable patterns
• Partials organization (_variables, _mixins, _base)

Touch Targets

• Minimum 44px tap target size on all interactive elements

Tailwind CSS

• Preferred styling approach for new projects
• Custom component extraction for repeated patterns
• Consistent spacing and sizing via design tokens
• Dark mode support where applicable

CSS-in-JS

• Styled-components or Emotion when component-scoped styles are needed
• Theme provider for consistent styling across app

CSS Security

• Content Security Policy compliance
• Avoid inline styles in production (CSP)
• Sanitized dynamic CSS generation
• Protection against CSS injection

Build Tools

• PostCSS for CSS processing
• Autoprefixer for browser compatibility
• PurgeCSS for unused style removal
• Stylelint for CSS linting

React / Next.js Patterns

Stack Requirements

• Next.js 15+ with App Router (required for new projects)
• TypeScript 5+ (mandatory)
• React 19+ functional components with hooks
• Tailwind CSS with shadcn/ui components (Material-UI or Ant Design as alternatives)

Architecture

• Small, single-responsibility components with proper TypeScript prop typing
• Custom hooks for reusable logic
• Proper error boundaries at page and feature level

State Management

Frontend is a Dumb Renderer

All data classification, grouping, and business logic belongs in the backend. The frontend receives pre-structured data and renders it. Keep business logic out of components.

Clean Data Structure Updates

When data structures change, update all consumers cleanly. Avoid re-exports and shims. Fix data structures end-to-end: backend models, API, frontend types, components.

Testing

• Jest + React Testing Library for component tests
• Cypress or Playwright for E2E
• MSW for API mocking
• Test component behavior, not implementation details

Browser Automation Safety

When using Playwright or any browser automation, avoid terminating the user's personal Chrome/Chromium instances. Always identify the correct Chrome process (Playwright-spawned) before terminating. Use headless mode when possible.

WordPress Standards

Stack Requirements

• WordPress 6.4+ with PHP 8.2+
• MySQL 8.0 with Redis caching
• Docker Compose deployment

Security

• Regular updates for core, themes, and plugins
• Security headers configured
• Access control properly set
• Backup procedures in place and tested

Content Workflow

• Markdown to WordPress content pipeline
• AI-generated content requires human review before publication

Node.js / Express

Project Structure

• Domain-organized routes and middleware
• Proper module organization with clear separation of concerns
• Configuration via environment variables

API Design

• RESTful principles with proper versioning
• Request validation on all endpoints
• Consistent error response format
• API documentation maintained

Security

• CORS configured per-environment
• Rate limiting on all public endpoints
• Security headers (Helmet.js or equivalent)
• Input validation and sanitization

Authentication

• JWT handling with proper expiry and refresh
• Password hashing (bcrypt, argon2)
• OAuth integration where needed
• Role-based access control

Performance

• Response caching where appropriate
• Async/await for all I/O operations
• Connection pooling for databases
• Proper logging and monitoring

Testing

• Unit tests for business logic
• Integration tests for API endpoints
• Proper mocking for external dependencies
• Error scenario coverage

Deployment

• Docker-based deployment
• Environment variables for configuration (secrets must not be hardcoded)
• Structured logging for observability
• Graceful shutdown on process signals

Python / Flask

Project Structure

• src/ layout with src/your_package_name/
• Tests in tests/ parallel to src/
• Configuration via environment variables or config/
• templates/ for Jinja2, static/ for assets

Code Style

• Black code formatting (88 char line length)
• isort for import sorting
• PEP 8 naming: snake_case functions/variables, PascalCase classes, UPPER_CASE constants
• Absolute imports over relative imports
• Type hints on all function parameters and return types

Flask Patterns

• Factory pattern (create_app())
• Blueprints for route organization
• Flask-SQLAlchemy for database
• Flask-Login for session management
• CSRF protection enabled
• Flask-RESTful for REST APIs

Security

• HTTPS in production
• CORS configured properly
• All user inputs sanitized
• OWASP guidelines followed
• Proper session configuration

Testing

• pytest with pytest-cov for coverage
• Fixtures for test setup
• pytest-mock for mocking
• All error scenarios covered

Dependencies

• Pin all dependency versions
• Separate dev dependencies from production
• Regular security vulnerability scanning
• Virtual environments (venv) required

Database Standards

Supported Stack

ORM Frameworks

Schema Design

• 3NF minimum normalization
• Table names: plural, snake_case (users, order_items)
• Column names: descriptive, snake_case (created_at, user_id, email_address)
• Primary keys: auto-increment integer preferred; UUID for distributed systems
• Denormalize only for proven read-heavy performance issues or reporting tables

Indexing

Create indexes on: foreign keys, WHERE clause columns, JOIN columns, ORDER BY columns, high-cardinality columns.

Avoid: over-indexing (slows writes), indexing low-cardinality columns (e.g., booleans), redundant indexes.

SQL Injection Prevention

Always use parameterized queries. Avoid string concatenation for SQL construction.

# Correct (SQLAlchemy)
user = session.query(User).filter(User.email == email).first()

Query Optimization

• SELECT specific columns instead of SELECT *
• Use EXISTS instead of COUNT(*) for existence checks
• Explicit JOINs instead of implicit (Cartesian product risk)
• JOINs over correlated subqueries
• LIMIT on large result sets
• Cursor-based pagination over large OFFSET
• EXPLAIN ANALYZE to verify query plans

N+1 Prevention

• Python/SQLAlchemy: joinedload() or subqueryload()
• Go/GORM: Preload()
• Node.js/Sequelize: include with eager loading

Connection Pooling

• Size: (CPU cores * 2) + disk spindles as starting point
• Enable pre-ping / health checks
• Set max_overflow, pool_timeout, pool_recycle appropriately
• Monitor active vs idle connections

Migrations

• Always version-controlled in git
• Do not modify existing migrations; create new ones instead
• Reversible (provide down migrations) when possible
• Test in dev/staging before production
• Keep schema and data migrations separate
• Tools: Alembic (Python), golang-migrate/atlas (Go), Sequelize CLI (Node.js)

Security

• Principle of least privilege for database accounts
• Separate accounts for app, admin, and migration roles
• Avoid using superuser accounts in application code
• SSL/TLS for all connections
• Encrypt sensitive columns (PII, passwords) at application level
• Use KMS for key management

Multi-Country Document Formatting

All business documents must use the correct format for their jurisdiction.

Rules

• Do not mix country contexts in a single document
• Validate country detection before generating any document
• Employment bonds: legal in India only, not applicable for USA/Canada
• Company stamps: required in India, CSS-based integration
• Country-specific templates for all legal/HR documents
• Letterhead: A4 for India, Letter for USA/Canada

Content Standards

Markdown

• Standard markdown syntax for all content files (no inline HTML/CSS except designated index pages)
• Clear, descriptive headers with logical hierarchy
• Relative links for internal references
• Consistent formatting within sections

Single Source of Truth

• Avoid duplicating content between files
• Define standards, processes, templates once in the authoritative location
• Reference the source everywhere else
• Before changes: check all related files for cross-references
• After changes: update all cross-references consistently
• Commit related changes together for atomic updates

StoryBrand Framework

All customer-facing content follows StoryBrand:

• Customer is the hero, not the company
• Value-driven messaging with clear problem/solution framing
• Clear calls to action on every page
• AI-generated content requires human review before publication

SEO

• Page titles: 50-60 characters, keyword-rich
• Meta descriptions: 150-160 characters
• Proper heading structure (single H1, logical H2+ hierarchy)
• Structured data markup (JSON-LD)
• XML sitemaps maintained
• Descriptive image file names

Brand and Legal

• Follow established brand voice, colors, typography, logo usage
• Include necessary disclaimers and legal notices
• Follow data privacy regulations (GDPR, CCPA)
• Regular content audits; test all links and forms; verify cross-device display

AI Decision Patterns

Model Selection

Fallback Policy

1. Start with local-llama-latest
2. Escalate to gpt5 or claude-4-sonnet (pick lower cost that meets thresholds)
3. Thresholds: accuracy >= 0.92, completeness >= 0.90, validation confidence >= 0.90
4. After two model failures at >= 90% accuracy: pause workflow, ask user for clarification

Zero-Code Principles

• Declarative over imperative: define WHAT, not HOW
• YAML-first development -- no static templates in the zero-code framework
• AI-driven synthesis: humans provide intent, AI provides implementation
• 4-phase pipeline: intent capture, pattern matching, generation, validation
• Security defined in YAML configurations, not code
• Quality targets: generation accuracy > 95%, deployment success > 98%, security compliance 100%

Operational Guardrails

Gateway API, Not Ingress

The platform uses HTTPRoute / Gateway / GRPCRoute. Do not reference Ingress resources.

Prefer Clean, Complete Implementations

Favor clean, complete implementations over quick fixes. Fix data structures end-to-end rather than adding shims.

Interactive Elements

• Clear visual feedback for all user interactions
• Loading states for all async operations
• Proper error states with actionable messages
• Smooth transitions; skeleton screens for loading
• Avoid layout shifts during state changes

Navigation

• Intuitive navigation with breadcrumbs for deep hierarchies
• Search functionality where appropriate
• Consistent navigation patterns across pages

Images and Media

• High-quality, optimized images (WebP preferred)
• Proper alt text on all images
• Lazy loading for non-critical content
• CDN delivery for static assets