coding-os 0.3.2__py3-none-any.whl

templates/nestjs/stack.yaml

@@ -0,0 +1,68 @@
+version: 1
+id: nestjs
+language: typescript
+label: "NestJS + TypeScript"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── package.json
+    ├── tsconfig.json
+    ├── nest-cli.json
+    └── src/
+        ├── main.ts              # NestFactory bootstrap (no logic)
+        ├── app.module.ts        # root module — wires feature modules only
+        ├── common/              # cross-cutting: filters, pipes, guards, interceptors
+        └── <feature>/           # one module per domain
+            ├── <feature>.module.ts
+            ├── <feature>.controller.ts   # thin — delegates to the provider
+            └── <feature>.service.ts      # business logic (the only layer that thinks)
+  notes: "controllers thin, providers own logic; one global exception filter is the ONLY error-response shaper; validation via a global ValidationPipe + class-validator DTOs"
+primary_skill: nestjs
+skills: [nestjs]
+
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/nestjs-service.md`"
+  SKILL_ROUTES: "Backend→`nestjs`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/nestjs-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && npm run lint && npm test`"
+  QUICK_ROUTING: |-
+    - NestJS controller / module task → [NestJS Service Playbook](./playbooks/nestjs-service.md)
+    - Guard / pipe / DTO validation → [NestJS Service Playbook](./playbooks/nestjs-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-NESTJS` → `./playbooks/nestjs-service.md`
+    - `REF:NESTJS-RULES` → `./engineering/nestjs-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-NESTJS", path: "./playbooks/nestjs-service.md", desc: "NestJS service playbook"}
+  - {code: "REF:NESTJS-RULES",    path: "./engineering/nestjs-rules.md", desc: "NestJS engineering rules"}
+
+routing_entries:
+  - "NestJS controller / module task → [NestJS Service Playbook](./playbooks/nestjs-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.ts"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "npx --yes eslint . && cd src/backend && npm run lint"}
+  - {name: test-backend, cmd: "cd src/backend && npm test"}
+
+verify:
+  - {glob: "src/backend/**/*.ts", suites: "lint-backend + test-backend", cmd: "npx --yes eslint . && cd src/backend && npm run lint && npm test"}
+
+dimensions:
+  - {name: "NestJS controller",     read_files: ["docs/playbooks/nestjs-service.md", "docs/engineering/nestjs-rules.md"]}
+  - {name: "Provider / service",    read_files: ["docs/engineering/nestjs-rules.md"]}
+  - {name: "Module / DI wiring",    read_files: ["docs/engineering/nestjs-rules.md"]}
+  - {name: "Pipe / DTO validation", read_files: ["docs/engineering/nestjs-rules.md", "docs/api-contracts/error-format.md"]}
+  - {name: "Guard / auth",          read_files: ["docs/engineering/nestjs-rules.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.ts"], primary: nestjs, secondary: [clean-code, backend-fundamentals, api-design, auth-patterns, security-web, testing-strategy, observability]}
+  - {globs: ["src/backend/**/*.service.ts", "src/backend/**/repositories/**/*.ts", "src/backend/**/db/**/*.ts"], primary: nestjs, secondary: [clean-code, db-design, backend-fundamentals]}
+  - {globs: ["src/backend/**/*.guard.ts", "src/backend/**/auth*.ts"], primary: nestjs, secondary: [auth-patterns, security-web, clean-code]}

templates/nextjs/rules/frontend.md

@@ -0,0 +1,18 @@
+---
+globs: ["src/frontend/**/*.{ts,tsx,css}", "src/frontend/**/*.js"]
+alwaysApply: false
+---
+
+# Next.js Frontend Rules (auto-loaded on src/frontend/**)
+
+When editing any file under `src/frontend/`, follow these standards:
+
+- **Server Components by default** — add `"use client"` only when you need state, effects, or browser APIs.
+- **Typed data boundaries** — every fetch uses a zod schema or explicit type; no `any`.
+- **Accessibility** — semantic HTML, labelled inputs, keyboard-reachable interactions.
+- **No layout shift** — fixed dimensions on images, reserved space for async content.
+- **Colocated tests** — `Component.tsx` + `Component.test.tsx` side by side.
+
+Canonical policy: `docs/engineering/frontend-rules.md`
+Playbook: `docs/playbooks/frontend-ui.md`
+Primary skill: `nextjs-react`

templates/nextjs/scaffold/docs/design/00-index.md

@@ -0,0 +1,23 @@
+<!-- domain:FRONTEND | layer:index | ssot:true | updated:{{DATE}} -->
+# Design System — Index
+
+Purpose: Navigation hub for the design system — colors, typography, spacing, components, and motion.
+Read when: Implementing or restyling UI components, or onboarding to the visual system.
+Skip when: The task is purely backend or doesn't touch visual presentation.
+Read next: The specific design doc relevant to your task.
+
+> Nav: [Docs Index](../00-index.md)
+
+## Files
+
+- [Colors & Tokens](./colors-tokens.md) — Color palette, semantic tokens, dark mode
+- [Typography & Spacing](./typography-spacing.md) — Font scale, spacing scale, layout grid
+- [Components & Patterns](./components-patterns.md) — Reusable component recipes
+- [Motion & Accessibility](./motion-accessibility.md) — Animations, transitions, a11y rules
+
+## Authoring Rules
+
+- Design tokens are SSOT. Tailwind config / CSS variables import from these docs.
+- Components defined here have a single canonical implementation in `src/frontend/src/components/`.
+- Accessibility is non-negotiable. See `../engineering/accessibility-web.md`.
+- When the design system evolves, update the doc and components in the same PR.

templates/nextjs/scaffold/docs/design/colors-tokens.md

@@ -0,0 +1,141 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:2026-03-13 -->
+
+# Colors & Tokens
+
+Purpose: Design token values — colors, semantic aliases, and dark-mode mappings.
+Read when: Task involves color selection, theme configuration, or design tokens.
+Skip when: Code-only change with no visual impact.
+Read next: Typography and spacing (typography-spacing.md) or components (components-patterns.md).
+
+> Nav: [Docs Index](../00-index.md) | [Style Guide](../../STYLE_GUIDE.md)
+
+---
+
+## 1. Theme Configuration
+
+### Default Mode
+
+- **Light mode is the DEFAULT**. Users see light mode on first visit.
+- Dark mode is only activated when user explicitly toggles.
+
+### Implementation
+
+```javascript
+// tailwind.config.ts
+darkMode: 'class', // NOT 'media'
+```
+
+- Store preference in `localStorage` with key `theme`
+- Respect `prefers-color-scheme` only on first visit if no stored preference
+- Apply `.dark` class to `<html>` element
+
+### Theme Toggle Component
+
+- **Location**: Header (desktop: right side near user menu, mobile: in hamburger menu)
+- **Icons**: Sun (light) / Moon (dark)
+- **Transition**: `transition-colors duration-200`
+- **Accessibility**: `aria-label="Toggle theme"`
+
+---
+
+## 2. Color Palette (CSS Variables)
+
+> [!CAUTION]
+> **All colors MUST be defined as raw RGB values** (e.g., `67 118 248`) not Hex.
+> This enables Tailwind's opacity modifier: `bg-brand-1/50` -> `rgba(67, 118, 248, 0.5)`
+
+> [!WARNING]
+> **Shadcn vs ExampleApp Colors**: Shadcn uses `--background` (white). ExampleApp uses `--bg` (#F6F7F7).
+> **Resolution**: Override Shadcn's `--background` to match `--bg` in globals.css.
+
+### 2.1 Brand Colors (Vibrant Gradient)
+
+| Token           | Light RGB     | Dark RGB     | Hex Reference     | Usage                 |
+| :-------------- | :------------ | :----------- | :---------------- | :-------------------- |
+| `--brand-1`     | `68 119 248`  | `68 119 248` | #4477F8           | Primary Blue          |
+| `--brand-2`     | `112 68 248`  | `112 68 248` | #7044F8           | Middle Purple         |
+| `--brand-3`     | `184 68 248`  | `184 68 248` | #B844F8           | End Pink/Purple       |
+| `--accent-soft` | `208 221 255` | `30 41 59`   | #D0DDFF / #1E293B | Background highlights |
+
+### 2.2 Surface & Backgrounds (Canvas)
+
+| Token         | Light RGB     | Dark RGB   | Description                      |
+| :------------ | :------------ | :--------- | :------------------------------- |
+| `--bg`        | `246 247 247` | `11 16 32` | Main window background           |
+| `--bg-canvas` | `228 230 229` | `7 11 22`  | App background outside container |
+| `--surface`   | `255 255 255` | `15 22 48` | Cards, Modals, Dropdowns         |
+| `--surface-2` | `248 248 248` | `18 27 58` | Nested sections, inputs          |
+
+### 2.3 Typography Colors
+
+| Token              | Light RGB     | Dark RGB      | Accessibility Note         |
+| :----------------- | :------------ | :------------ | :------------------------- |
+| `--text`           | `13 14 19`    | `238 241 247` | WCAG AAA on Surface        |
+| `--text-secondary` | `91 93 94`    | `199 205 219` | For subheaders             |
+| `--text-muted`     | `138 139 144` | `167 175 194` | For metadata, placeholders |
+
+### 2.4 Semantic Feedback
+
+| Type        | Light RGB    | Dark RGB      | Hex     | Usage         |
+| :---------- | :----------- | :------------ | :------ | :------------ |
+| **Success** | `22 163 74`  | `34 197 94`   | #16A34A | Success toast |
+| **Warning** | `245 158 11` | `251 191 36`  | #F59E0B | Alerts        |
+| **Error**   | `239 68 68`  | `248 113 113` | #EF4444 | Form errors   |
+| **Info**    | `14 165 233` | `56 189 248`  | #0EA5E9 | Hints         |
+
+### 2.5 Tailwind Config Pattern
+
+```javascript
+// tailwind.config.ts
+colors: {
+  'brand-1': 'rgb(var(--brand-1) / <alpha-value>)',
+  // ...
+},
+boxShadow: {
+  'premium': '0 10px 30px -10px rgb(var(--brand-1) / 0.15)', // Dynamic Shadow
+}
+```
+
+### 2.6 globals.css Pattern
+
+```css
+:root {
+  --brand-1: 68 119 248;
+  --brand-2: 112 68 248;
+  --brand-3: 184 68 248;
+  --bg: 246 247 247;
+  --surface: 255 255 255;
+  /* ... etc */
+}
+
+.dark {
+  --brand-1: 68 119 248;
+  --brand-2: 112 68 248;
+  --brand-3: 184 68 248;
+  --bg: 11 16 32;
+  --surface: 15 22 48;
+  /* ... etc */
+}
+```
+
+---
+
+## 3. Visual Effects
+
+### 3.1 Gradients
+
+Used sparingly for emphasis.
+
+- **CTA Gradient**: `linear-gradient(135deg, #4477f8 0%, #7044f8 50%, #b844f8 100%)`
+- **Text Gradient (Hero)**: `bg-clip-text text-transparent bg-gradient-to-r from-brand-1 via-brand-2 to-brand-3`
+- **Surface Glow**: Subtle glow behind active cards in Dark Mode
+
+### 3.2 Shadows (Depths)
+
+- **Focus Ring**: `ring-4 ring-brand-1/20`
+- **Float**: `shadow-xl shadow-brand-1/10` (for sticky elements)
+
+### 3.3 Blur (Glassmorphism)
+
+- Used on **Sticky Header** and **Toast Notifications**
+- Class: `backdrop-blur-md bg-surface/80`

templates/nextjs/scaffold/docs/design/components-patterns.md

@@ -0,0 +1,159 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:2026-03-13 -->
+
+# Components & Patterns
+
+Purpose: Reusable UI component patterns, states, and composition rules.
+Read when: Task involves building or styling UI components.
+Skip when: Layout or color adjustments alone.
+Read next: Colors (colors-tokens.md), typography (typography-spacing.md), or motion (motion-accessibility.md).
+
+> Nav: [Docs Index](../00-index.md) | [Style Guide](../../STYLE_GUIDE.md)
+
+---
+
+## 1. Design Philosophy
+
+### Visual Excellence Standard
+
+ExampleApp's design must feel **premium, modern, and conversion-focused**.
+
+> [!TIP]
+> Think like an experienced graphic designer with knowledge of:
+>
+> - Sales psychology & CRO (Conversion Rate Optimization)
+> - 3D elements & abstract shapes for visual interest
+> - Micro-animations for engagement
+> - Premium color palettes (no generic red/blue/green)
+
+### Design Principles
+
+1. **Wow Factor**: First impression must impress - use gradients, subtle animations, glassmorphism
+2. **Trust Building**: Social proof, security badges, professional typography
+3. **Clear Hierarchy**: Guide the eye to CTAs with size, color, and whitespace
+4. **Mobile Excellence**: 60%+ traffic is mobile - design mobile-first
+5. **Fast Perceived Performance**: Skeleton loaders, optimistic UI, smooth transitions
+
+### What to Avoid
+
+- Generic/flat designs
+- Default browser fonts
+- Plain solid color backgrounds
+- Static, lifeless interfaces
+- Placeholder images (use generated or real assets)
+
+### What to Embrace
+
+- Curated color harmonies (HSL-based, not plain hex)
+- Subtle gradients and shadows
+- Micro-interactions (hover effects, smooth transitions)
+- Modern typography (Baloo 2 + Inter)
+- Glassmorphism for overlays (when appropriate)
+- Abstract decorative elements (subtle, not distracting)
+
+---
+
+## 2. Site Branding
+
+- **Site Name**: `ExampleApp` (not "Example" or "example")
+- **Logo Text**: "ExampleApp" or "Example App" (with space for readability)
+- **Domain**: example.com
+
+---
+
+## 3. Buttons
+
+The most critical conversion element.
+
+### Primary (Money Button)
+
+- **Background**: `bg-gradient-to-r from-brand-1 to-brand-3`
+- **Text**: White, Bold (Inter Medium/Semibold)
+- **Visuals**: Mild shadow `shadow-lg`, rounded `rounded-full` or `rounded-xl`
+- **Hover**: Brightness up / Scale 1.05
+
+### Secondary (Outline)
+
+- **Border**: `border border-border`
+- **Background**: Transparent (hover: surface-2)
+- **Text**: `text-text-secondary` (hover: text-text)
+
+### Ghost (Link)
+
+- **Background**: None
+- **Text**: `text-text-muted` (hover: text-brand-1)
+
+---
+
+## 4. Cards (Surface)
+
+- **Base**: `bg-surface` border `border-border`
+- **Shadow**: `shadow-sm` (default) -> `shadow-md` (hover)
+- **Radius**: `rounded-2xl` (Standard for Containers/Cards)
+- **Padding**: `p-6` (default)
+- **Inputs/Buttons**: `rounded-xl` (Standard for Interactive Elements)
+- **Borders**: Thin, crisp borders (`1px`) in light mode
+
+---
+
+## 5. Loading States
+
+**Skeleton Loaders** are preferred over spinners for initial load.
+
+- **Animation**: `animate-pulse`
+- **Color**: `bg-muted` (or `bg-surface-2`)
+- **Radius**: Match the content being loaded (e.g. `rounded-full` for avatars)
+
+```tsx
+<div className="space-y-2">
+  <div className="h-4 w-[250px] animate-pulse rounded bg-muted" />
+  <div className="h-4 w-[200px] animate-pulse rounded bg-muted" />
+</div>
+```
+
+---
+
+## 6. Empty States
+
+Always provide a path forward.
+
+- **Visual**: Icon or Illustration
+- **Text**: Clear "Status" + "Solution"
+- **Action**: Button to resolve/create
+
+---
+
+## 7. Design Tradeoffs
+
+> Every philosophy accepts certain tradeoffs. Being explicit prevents surprise.
+
+| We Choose           | Over          | Because                          |
+| :------------------ | :------------ | :------------------------------- |
+| **Opinionated**     | Neutral       | Memorable > forgettable          |
+| **Consistent**      | Flexible      | Maintainable > one-off solutions |
+| **Bold**            | Safe          | Standing out > blending in       |
+| **Semantic Tokens** | Direct Values | Scalability > initial speed      |
+| **Fewer Options**   | More Options  | Clarity > choice paralysis       |
+| **Performance**     | Features      | Fast basics > slow extras        |
+| **Mobile-First**    | Desktop-First | 60%+ traffic is mobile           |
+
+---
+
+## 8. Anti-Patterns
+
+| Anti-Pattern               | Why Harmful                   | Alternative                         |
+| :------------------------- | :---------------------------- | :---------------------------------- |
+| **Hardcoded colors**       | Impossible to theme           | Use semantic tokens                 |
+| **Inconsistent spacing**   | Creates visual noise          | Use 4pt spacing scale               |
+| **Too many fonts**         | Looks chaotic                 | Max 2 fonts                         |
+| **Purple AI gradients**    | Overused, generic             | Distinctive palette                 |
+| **Motion without purpose** | Distracting, unprofessional   | Animate with intent                 |
+| **Ignoring dark mode**     | Excludes users                | Design both modes                   |
+| **className overrides**    | Unmaintainable                | Create component variants           |
+| **Missing focus states**   | Accessibility failure         | Always show focus rings             |
+| **Placeholder images**     | Unprofessional                | Generate or use real assets         |
+| **Generic stock photos**   | Feels corporate/fake          | Custom or AI-generated              |
+| **CSS Media Query Hacks**  | Breaks composition            | Use standard Tailwind               |
+| **Double Mobile Headers**  | Confusing UI, double triggers | Single global header                |
+| **Low Z-Index Modals**     | Hides under sticky headers    | Use `z-max` (100)                   |
+| **Horizontal Overflow**    | White bars on mobile edges    | `overflow-x-hidden` + `break-words` |
+| **Tight Mobile Padding**   | Cramped, cheap feel           | Min `px-6` (24px) padding           |

templates/nextjs/scaffold/docs/design/motion-accessibility.md

@@ -0,0 +1,137 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:2026-03-13 -->
+
+# Motion & Accessibility
+
+Purpose: Animation guidelines, reduced-motion support, and WCAG compliance.
+Read when: Task involves animations, transitions, or accessibility compliance.
+Skip when: Static layouts or non-interactive features.
+Read next: Components (components-patterns.md) or the frontend-ui playbook.
+
+> Nav: [Docs Index](../00-index.md) | [Style Guide](../../STYLE_GUIDE.md)
+
+---
+
+## 1. Motion & Animation
+
+### 1.1 Motion Philosophy
+
+- Animation should **signal state changes**, **guide attention**, and **create delight**
+- Never distract or delay the user
+- The absence of _expected_ motion feels broken
+- One well-crafted hero animation > twenty scattered micro-interactions
+
+### 1.2 Timing Scale
+
+| Name        | Duration | Tailwind       | Use Case                     |
+| :---------- | :------- | :------------- | :--------------------------- |
+| **Instant** | 50ms     | `duration-50`  | Micro-feedback (hover color) |
+| **Fast**    | 150ms    | `duration-150` | UI feedback (button click)   |
+| **Normal**  | 300ms    | `duration-300` | Standard transitions         |
+| **Slow**    | 500ms    | `duration-500` | Complex animations           |
+| **Hero**    | 700ms+   | `duration-700` | Hero section animations      |
+
+### 1.3 Easing Functions
+
+| Name          | CSS Value                      | Use Case              |
+| :------------ | :----------------------------- | :-------------------- |
+| `ease-out`    | `cubic-bezier(0, 0, 0.2, 1)`   | Elements entering     |
+| `ease-in`     | `cubic-bezier(0.4, 0, 1, 1)`   | Elements exiting      |
+| `ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | On-screen movement    |
+| `spring`      | Framer Motion                  | Playful, organic feel |
+
+### 1.4 Implementation (Framer Motion)
+
+```tsx
+// Entrance animation
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.5, ease: "easeOut" }}
+>
+```
+
+---
+
+## 2. Performance Targets
+
+> [!IMPORTANT]
+> Speed and stability are **user experience concerns**, not just technical concerns.
+
+| Metric                             | Target     | Tool                    |
+| :--------------------------------- | :--------- | :---------------------- |
+| **LCP** (Largest Contentful Paint) | < 2.5s     | Lighthouse              |
+| **FCP** (First Contentful Paint)   | < 1.5s     | Lighthouse              |
+| **CLS** (Cumulative Layout Shift)  | < 0.1      | Lighthouse              |
+| **Animation Frame Rate**           | 60fps      | DevTools                |
+| **Bundle Size (First Load)**       | < 200KB JS | `@next/bundle-analyzer` |
+
+### Performance-Impacting Decisions
+
+- Lazy load images below the fold (`loading="lazy"`)
+- Use `next/image` with explicit `sizes`
+- Preload critical fonts
+- Code-split large components with `next/dynamic`
+- Don't load heavy animations on mobile
+
+---
+
+## 3. Accessibility Requirements
+
+> [!CAUTION]
+> Accessibility is not a feature -- it's the **foundation**.
+
+### Non-Negotiable Requirements
+
+| Element                 | Requirement                                                    |
+| :---------------------- | :------------------------------------------------------------- |
+| **Color Contrast**      | WCAG AA (4.5:1 for text, 3:1 for large text)                   |
+| **Focus States**        | Visible, high-contrast focus rings on ALL interactive elements |
+| **Touch Targets**       | Minimum 44x44px                                                |
+| **Keyboard Navigation** | All interactive elements reachable via Tab                     |
+| **Semantic HTML**       | Proper `<h1>`-`<h6>` hierarchy, landmarks (`<main>`, `<nav>`)  |
+| **Alt Text**            | Meaningful descriptions for all images                         |
+| **ARIA Labels**         | For icons and non-text elements                                |
+
+### Focus Ring Standard
+
+```css
+/* Default focus ring */
+.focus-visible:focus {
+  outline: 2px solid rgb(var(--brand-1));
+  outline-offset: 2px;
+}
+```
+
+---
+
+## 4. Responsive Design Patterns
+
+> [!IMPORTANT]
+> Use standard Tailwind breakpoints. Ensure server-side rendering matches client structure to avoid hydration errors.
+
+### 4.1 Breakpoints
+
+- **Mobile First**: Default styles are mobile.
+- **Tablet**: `md:` (768px+)
+- **Desktop**: `lg:` (1024px+)
+- **Wide**: `xl:` (1280px+)
+
+### 4.2 Common Patterns
+
+```tsx
+// Stack on mobile, Row on desktop
+<div className="flex flex-col md:flex-row gap-4">
+
+// Hide on mobile, Show on desktop
+<div className="hidden md:block">
+
+// Container Padding (Safe Area)
+// Must be px-6 on mobile for breathing room
+<div className="px-6 sm:px-8 lg:px-12">
+```
+
+### 4.3 Layout Safeguards
+
+1. **Global Scroll Lock**: `html, body { overflow-x: hidden; }` must be applied to prevent horizontal scroll on narrow devices.
+2. **Text Constraint**: Use `break-words` on large headings.
+3. **Narrow Screen Logic**: Hide non-essential text/icons on screens < 340px (Galaxy Fold).

templates/nextjs/scaffold/docs/design/typography-spacing.md

@@ -0,0 +1,107 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:2026-03-13 -->
+
+# Typography & Spacing
+
+Purpose: Font stacks, type scale, and spacing/grid rules.
+Read when: Task involves typography, spacing, layout, or responsive grid.
+Skip when: Color or component styling without layout changes.
+Read next: Colors and tokens (colors-tokens.md) or components (components-patterns.md).
+
+> Nav: [Docs Index](../00-index.md) | [Style Guide](../../STYLE_GUIDE.md)
+
+---
+
+## 1. Font Families
+
+- **Headings**: `Baloo 2` (Rounded, Friendly, Modern) — Weights: 700 (Bold)
+- **Body**: `Inter` (Clean, Legible, Standard) — Weights: 400 (Regular), 500 (Medium), 600 (SemiBold)
+
+## 2. Type Scale (Tailwind)
+
+| Class       | Size (rem) | Size (px) | Line Height | Usage                    |
+| :---------- | :--------- | :-------- | :---------- | :----------------------- |
+| `text-xs`   | 0.75       | 12px      | 1rem        | Badges, Microcopy        |
+| `text-sm`   | 0.875      | 14px      | 1.25rem     | UI Labels, Metadata      |
+| `text-base` | 1          | 16px      | 1.5rem      | **Default Body Text**    |
+| `text-lg`   | 1.125      | 18px      | 1.75rem     | Intro paragraphs         |
+| `text-xl`   | 1.25       | 20px      | 1.75rem     | Section Headers (H3)     |
+| `text-2xl`  | 1.5        | 24px      | 2rem        | Card Titles (H2)         |
+| `text-3xl`  | 1.875      | 30px      | 2.25rem     | Page Titles (H1 Mobile)  |
+| `text-4xl`  | 2.25       | 36px      | 2.5rem      | Page Titles (H1 Desktop) |
+| `text-5xl`  | 3          | 48px      | 1           | Hero Headings            |
+
+---
+
+## 3. Spacing & Layout
+
+We follow a **4pt grid system** (Tailwind default).
+
+### 3.1 Container Configuration
+
+```javascript
+// tailwind.config.ts
+container: {
+  center: true,
+  padding: {
+    DEFAULT: '1rem',    // 16px mobile
+    sm: '1.5rem',       // 24px small
+    lg: '2rem',         // 32px large
+    xl: '2rem',
+    '2xl': '2rem',
+  },
+  screens: {
+    '2xl': '1400px',    // Max container width (Audit Fix)
+  },
+}
+```
+
+### 3.2 Section Spacing (`py-`)
+
+- **Tight**: `py-8` (32px)
+- **Normal**: `py-16` (64px) — **Standard Section**
+- **Loose**: `py-24` (96px) — **Hero / Feature Splits**
+
+### 3.3 Gap
+
+- **Stack (Vertical)**: `space-y-4` (Forms), `space-y-6` (Content)
+- **Grid (Horizontal)**: `gap-6` (Cards), `gap-8` (Columns)
+
+---
+
+## 4. Z-Index Layering System
+
+> [!IMPORTANT]
+> All z-index values MUST follow this scale. Do not use arbitrary values.
+
+| Layer       | Z-Index | Tailwind Class | Elements                           |
+| :---------- | :------ | :------------- | :--------------------------------- |
+| **Base**    | 0       | `z-0`          | Page content, sections             |
+| **Raised**  | 10      | `z-raised`     | Cards with hover, dropdowns        |
+| **Sticky**  | 40      | `z-sticky`     | Sticky bottom bar, floating CTAs   |
+| **Header**  | 50      | `z-header`     | Site header (always above content) |
+| **Overlay** | 60      | `z-overlay`    | Backdrop for modals                |
+| **Modal**   | 70      | `z-modal`      | Modal dialogs                      |
+| **Toast**   | 80      | `z-toast`      | Toast notifications                |
+| **Tooltip** | 90      | `z-tooltip`    | Tooltips, popovers                 |
+| **Max**     | 100     | `z-max`        | **Mobile Nav**, Emergency overlays |
+
+### Z-Index Rules
+
+1. **Header (`z-header`)** must ALWAYS be above content sections.
+2. **Sticky bars** use `z-sticky` (below header).
+3. **Mobile Nav / Modals** MUST use `z-max` (100) to overlay sticky headers.
+4. **Use Semantic Tokens**: `z-modal` instead of `z-[70]`.
+5. **Stacking context**: Use `isolate` class on parent containers if needed.
+
+---
+
+## 5. Grid System
+
+We use a **12-column grid** for main layouts.
+
+```tsx
+<div className="grid grid-cols-4 md:grid-cols-8 lg:grid-cols-12 gap-6">
+  <div className="col-span-4">Sidebar</div>
+  <div className="col-span-8">Content</div>
+</div>
+```