CushLabs.ai — Design & Technical Specification

A comprehensive design document covering branding, visual system, language implementation, and JavaScript functionality.

1. Brand Identity

Brand Name

CushLabs.ai

Brand Positioning

AI consulting and modern software development studio targeting SMBs. Positioned as experienced, technically sophisticated, and approachable — expertise without intimidation.

Brand Voice

• Professional but personable (first-person "I" rather than corporate "we")
• Technical depth communicated accessibly
• Confident without arrogance
• Modern and forward-looking

2. Color Palette

Primary Colors

Chart Palette (Forecast + Range)

The chart series colors are implemented as CSS variables in app/globals.css so they stay consistent across light/dark mode:

Secondary / UI Colors

Gradient & Glow Effects

3. Typography

Font Stack

Type Scale (Fluid)

All sizes use clamp() for smooth scaling between mobile (320px) and desktop (1440px+):

Typography Settings

4. Layout System

Container

Spacing Scale (Fluid)

Grid System

Features Grid (2×2):

• Fixed 2-column layout: grid-template-columns: repeat(2, 1fr)
• Max width: 900px
• Gap: --space-lg
• Breakpoint: Single column below 600px

5. Current App Implementation Notes

Language (EN/ES)

• UI strings are sourced from lib/i18n/translations.ts.
• Components use useTranslation(language).
• Language is persisted in the Zustand store (lib/store.ts).

Theme (Light/Dark)

• Theme tokens are implemented via CSS variables in app/globals.css.
• Tailwind color tokens resolve to CSS variables (tailwind.config.js).
• Theme defaults to system preference when no persisted theme exists, and persists via Zustand.

6. JavaScript / Interaction Notes

• This project is implemented as a Next.js (App Router) application.
• Client-side interactivity is handled within React components.

Notes

• Any animation/interaction patterns should be implemented as React components.
• Prefer small, composable UI pieces and keep business logic outside UI components.

7. Animation Specifications

Entry Animations

Scroll Animations

Ambient Animations

Easing Functions

8. Responsive Breakpoints

9. Accessibility Compliance

WCAG 2.1 AA Checklist

Reduced Motion Support

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

10. Technical SEO Implementation (Current)

This app relies on Next.js metadata rather than manual <meta> tags inside components.

Metadata sources

• app/layout.tsx exports metadata (site-wide defaults).
• app/income-planner/page.tsx exports page-level metadata for the tool.
• app/docs/[slug]/page.tsx uses generateMetadata() from the markdown frontmatter.

Notes

• Open Graph / Twitter metadata is currently minimal; if we want richer share cards, add openGraph + twitter fields in app/layout.tsx and use a real production URL.
• The docs system already supports per-doc titles and descriptions via frontmatter.

11. Documentation Files

• README.md (root) — Setup and overview
• PRD.md (root) — Product requirements
• docs/BRAND.md — Brand strategy
• docs/DESIGN.md — Design system
• docs/ROADMAP.md — Roadmap
• docs/PREDEPLOY_AUDIT.md — Deployment checklist

12. Version History

Document maintained by CushLabs.ai