# Cora Design System
Version: 1.1.0
Updated: 2026-10-13
Canonical: https://heycora.in/design-system/
Source: cora-frontend/lib/design-system.ts

Public component library and machine-first design contract for Cora marketing and product development. Inspect visual recipes, reuse shared primitives, preserve shipped behavior and make deviations explicit.

## Start here
Before any Cora UI change, read cora-frontend/lib/design-system.ts (or /design-system/manifest.json and /design-system/llms.txt), choose marketing or workspace profile, reuse existing shells and documented primitives, preserve all states and mobile sheet rules, run npm run check:design-system in cora-frontend, and record any intentional design exception.

Baseline: Inherited monochromatic design direction and existing executable product patterns. This release consolidates them; it does not claim every historical implementation is compliant.

Approval boundary: New accessible status colors, minimum target sizes, semantic tokens and reusable primitives are implementation recommendations introduced with this contract. Changes to brand direction require explicit owner approval.

Precedence:
1. Current user instructions
2. Applicable repository instructions and accessibility requirements
3. This canonical contract and surface profile
4. Feature-local implementation and its documented exceptions
5. Legacy showcase and token files (historical only)

## Machine exports
- manifest: /design-system/manifest.json
- instructions: /design-system/llms.txt
- stylesheet: /design-system/tokens.css

## Version history
### 1.1.0 (2026-10-13)
- Add a public visual catalog of 24 source-backed specimens with variants, states, usage and structural examples.
- Distinguish reusable production primitives from composition recipes; preserve all existing token semantics and export endpoints.

### 1.0.0 (2026-10-13)
- Consolidate the marketing and workspace design contract, semantic tokens, component rules, five reusable primitives and generated machine exports.

## Change protocol
1. Read this manifest and the relevant profile before editing.
2. Inspect the existing feature, reuse its shell, and choose documented components.
3. Use named semantic tokens and reusable primitives; do not duplicate values.
4. If a new pattern is needed, update this source, component, states and rationale together.
5. Increment version: patch for corrections, minor for additive patterns, major for changed semantics.
6. Run check:design-system and build; inspect desktop, 390px mobile, keyboard and neighboring routes.
7. Document unresolved deviations; do not silently restyle unrelated modules.

## Principles
### P01: Quiet surfaces, clear hierarchy
Use Zinc, whitespace, typography and thin structural borders. No colored gradients, decorative emojis, heavy outlines or excessive shadows in operational UI.

### P02: Meaning before decoration
Status color is reserved for success, warning and error. Always pair color with text or an icon. Brand artwork and editorial accents stay in their established marketing contexts.

### P03: One source, two surfaces
Marketing and workspace share semantics and interaction principles while retaining their actual typography and canvas. Do not impose the marketing font on the product.

### P04: Every state is a design decision
Specify default, hover, focus, selected, disabled, loading, empty, error and success before a feature is complete.

### P05: Mobile is a first-class workflow
Use vertical sheets, explicit close controls, safe-area padding and reachable actions. Never force an off-canvas side drawer on a narrow screen.

### P06: Preserve trust and privacy
Use fictional names and sample records in public examples. Do not expose owner names, credentials, internal account data or real customer information.

## Surface profiles
### Marketing site (existing-baseline)
General Sans, expressive scale, white surfaces and monochromatic actions. Serif and handwritten accents belong to existing editorial hero treatments only. Do not add them to forms or data.
Stack: Next.js App Router / React / Tailwind
Font: --cora-font-marketing
Canvas: --cora-bg
Reuse: components/layout/Navbar.tsx; components/layout/Footer.tsx; components/tools/ToolPageShell.tsx; components/tools/framework/ToolContainer.tsx
Sources: cora-frontend/styles/globals.css; cora-frontend/tailwind.config.ts; cora-frontend/app/layout.tsx

### Product workspace (existing-baseline)
Inter for operational UI, JetBrains Mono for identifiers, compact hierarchy and tonal selection. Current workspace canvas is cream; dark canvas is #0c0c0e. Mobile sheets slide vertically. Keep industry labels dynamic.
Stack: WordPress plugin / PHP / JavaScript / Tailwind
Font: --cora-font-workspace
Canvas: --cora-canvas
Reuse: window.coraShowToast; includes/workspace-header.php; Existing feature-local sheet and table markup
Sources: app/public/wp-content/plugins/cora-workspace/assets/css/admin-style.css; app/public/wp-content/plugins/cora-workspace/admin-dashboard.php; .agents/AGENTS.md

## Audit scope
Repository source audit of marketing components, product views, styles, existing tokens, and instructions. The new route is browser-verified separately; this is not a claim that every existing product workflow has been visually tested.
287 distinct six-digit colors and 64 arbitrary max-width values appear in frontend source, including artwork and third-party logos. These counts demonstrate decentralization, not that every value is an error.
Migrate touched features incrementally. No global restyling or changes to authenticated workspace behavior are part of this release.

## Product and feature patterns
Workspace paths below resolve under app/public/wp-content/plugins/cora-workspace unless they begin with cora-frontend.
### Shell, settings and permissions
Persistent navigation, profile popover, dynamic permissions, explicit unsaved-change save bar; no unscoped CSS.
Sources: admin-dashboard.php; views/view-feature-hub.php; views/view-cora-roles.php; views/view-settings-suite.php

### CRM, clients and pipeline
Shared filter state across table/board; industry-aware labels; labelled status and keyboard alternative to drag-and-drop.
Sources: views/view-leads.php; views/view-clients.php

### Tasks, projects and portfolio
Consistent detail panels, checklists and activity; preserve confidentiality and selected-record context.
Sources: views/view-client-task-manager.php; views/view-projects.php; cora-frontend/app/portfolio/

### Content, inbox and automation
Separate draft, processing, published and failed states. Preserve editor content; show recoverable service errors.
Sources: views/view-content-suite.php; views/view-emails.php; views/view-inbox.php; views/view-automations.php

### Media, proofing and galleries
Aspect ratio presets 1:1 / 4:3 / 16:9, progressive previews, explicit selection and upload state; preserve image colors.
Sources: views/view-media.php; views/view-media-editor.php; public-gallery-view.php

### Documents and signatures
Guided creation, labelled signature controls, audit state. Authored document fonts are content and remain outside interface typography restrictions.
Sources: views/view-vault.php; public-doc-view.php

### Canvas and visual builder
User-designed color and typography are an intentional exception; editor chrome stays neutral. Preserve autosave and selected-node context.
Sources: views/view-canvas.php; views/view-visual-builder.php

### Finance, inventory and scheduling
Tabular values, explicit currency/tax/timezone, empty states and permissions; equipment/listing terminology derives from industry.
Sources: views/view-financials.php; views/view-equipment.php; views/view-crew-scheduler.php

### Forms, reviews and client portals
Visible labels and validation; client content retains its identity while functional controls follow the shared contract.
Sources: views/view-forms.php; views/view-review-acquisition.php; public-form-view.php; public-client-portal.php

### Public marketing and knowledge
Reuse existing hero, editorial and tool shells. Neutral controls coexist with established scenic artwork and authentic brand logos.
Sources: cora-frontend/components/hero/; cora-frontend/components/docs/; cora-frontend/components/tools/framework/

## Reusable primitive API
### Sheet
Import: @/components/design-system/primitives
Props: open: boolean; onClose: () => void; title: string; placement?: sheet | modal | drawer (default: sheet); footer?: ReactNode; children: ReactNode
Tokens: --cora-bg, --cora-border, --cora-backdrop, --cora-radius-2xl, --cora-drawer-width
Example: <Sheet open={isOpen} onClose={() => setIsOpen(false)} title="Project details" placement="drawer">…</Sheet>

### Button
Import: @/components/design-system/primitives
Props: variant?: primary | secondary | ghost | danger; loading?: boolean; all native button props
Tokens: --cora-action, --cora-on-action, --cora-control-height, --cora-radius-lg
Example: <Button variant="primary" loading={isSaving} onClick={save}>Save changes</Button>

### TextField
Import: @/components/design-system/primitives
Props: label: string; hint?: string; error?: string; id?: string; all native input props
Tokens: --cora-bg, --cora-border-strong, --cora-danger, --cora-text-body
Example: <TextField label="Project name" hint="Visible to your team" required />

### Badge
Import: @/components/design-system/primitives
Props: tone?: neutral | success | warning | danger; children: ReactNode
Tokens: --cora-selected, --cora-success, --cora-warning, --cora-danger
Example: <Badge tone="success">Active</Badge>

### Card
Import: @/components/design-system/primitives
Props: all native div props; children: ReactNode
Tokens: --cora-bg, --cora-border, --cora-radius-xl, --cora-space-6
Example: <Card><h3>Project summary</h3><p>Ready for review.</p></Card>

## Tokens
- --cora-zinc-50: #fafafa [palette] — Neutral reference 50; prefer semantic tokens in components.
- --cora-zinc-100: #f4f4f5 [palette] — Neutral reference 100; prefer semantic tokens in components.
- --cora-zinc-200: #e4e4e7 [palette] — Neutral reference 200; prefer semantic tokens in components.
- --cora-zinc-300: #d4d4d8 [palette] — Neutral reference 300; prefer semantic tokens in components.
- --cora-zinc-400: #a1a1aa [palette] — Neutral reference 400; prefer semantic tokens in components.
- --cora-zinc-500: #71717a [palette] — Neutral reference 500; prefer semantic tokens in components.
- --cora-zinc-600: #52525b [palette] — Neutral reference 600; prefer semantic tokens in components.
- --cora-zinc-700: #3f3f46 [palette] — Neutral reference 700; prefer semantic tokens in components.
- --cora-zinc-800: #27272a [palette] — Neutral reference 800; prefer semantic tokens in components.
- --cora-zinc-900: #18181b [palette] — Neutral reference 900; prefer semantic tokens in components.
- --cora-zinc-950: #09090b [palette] — Neutral reference 950; prefer semantic tokens in components.
- --cora-white: #ffffff [palette] — Pure light surface / inverse text.
- --cora-cream: #FBFAF7 [palette] — Existing workspace canvas and editorial backdrop; never a colored action.
- --cora-workspace-dark: #0c0c0e [palette] — Current dark workspace canvas; cards remain neutral raised surfaces.
- --cora-canvas: #ffffff [semantic] — Surface-profile page canvas; workspace overrides this to cream or its dark canvas.
- --cora-bg: #ffffff [semantic] — Page and control surface.
- --cora-surface: #fafafa [semantic] — Secondary surface.
- --cora-selected: #f4f4f5 [semantic] — Tonal hover and selection.
- --cora-border: #e4e4e7 [semantic] — One-pixel structural borders.
- --cora-border-strong: #71717a [semantic] — Accessible input boundary; never heavy card selection. Recommended for new controls.
- --cora-text: #09090b [semantic] — Primary text.
- --cora-muted: #52525b [semantic] — Supporting text on light surfaces.
- --cora-subtle: #71717a [semantic] — Metadata; do not reduce opacity on small text.
- --cora-action: #09090b [semantic] — Primary action / dark icon tile.
- --cora-on-action: #ffffff [semantic] — Text on primary action.
- --cora-action-hover: #27272a [semantic] — Primary action hover.
- --cora-focus: #52525b [semantic] — Visible keyboard focus; accessibility exception to decorative outline prohibition.
- --cora-success: #166534 [semantic] — Legible success text; always include label or icon.
- --cora-success-bg: #f0fdf4 [semantic] — Success surface only.
- --cora-warning: #854d0e [semantic] — Legible warning text; never the primary CTA.
- --cora-warning-bg: #fefce8 [semantic] — Warning surface only.
- --cora-danger: #b91c1c [semantic] — Error / destructive text.
- --cora-danger-bg: #fef2f2 [semantic] — Error surface only.
- --cora-font-marketing: 'General Sans', var(--font-sans, Inter), -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif [typography] — Marketing body and headings; retain current runtime font.
- --cora-font-workspace: var(--font-sans, Inter), -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif [typography] — Operational workspace text.
- --cora-font-ui: var(--cora-font-marketing) [typography] — Active surface font. Override through data-cora-profile.
- --cora-font-code: var(--font-mono, 'JetBrains Mono'), Menlo, Consolas, monospace [typography] — Code, identifiers, token values; use tabular figures for numeric data.
- --cora-text-caption: 0.75rem [type scale] — Role: caption. Base rem assumes 16px; respect browser zoom.
- --cora-text-code: 0.8125rem [type scale] — Role: code. Base rem assumes 16px; respect browser zoom.
- --cora-text-small: 0.875rem [type scale] — Role: small. Base rem assumes 16px; respect browser zoom.
- --cora-text-body: 1rem [type scale] — Role: body. Base rem assumes 16px; respect browser zoom.
- --cora-text-h3: 1.125rem [type scale] — Role: h3. Base rem assumes 16px; respect browser zoom.
- --cora-text-h2: 1.5rem [type scale] — Role: h2. Base rem assumes 16px; respect browser zoom.
- --cora-text-h1: 2rem [type scale] — Role: h1. Base rem assumes 16px; respect browser zoom.
- --cora-text-display: 3rem [type scale] — Role: display. Base rem assumes 16px; respect browser zoom.
- --cora-space-0: 0px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-1: 4px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-2: 8px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-3: 12px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-4: 16px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-5: 20px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-6: 24px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-8: 32px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-10: 40px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-12: 48px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-16: 64px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-20: 80px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-space-24: 96px [spacing] — Four-pixel rhythm; choose by relationship, not arbitrary decoration.
- --cora-radius-sm: 6px [radius] — Controls: md/lg; cards: xl; sheets: 2xl; status: pill.
- --cora-radius-md: 8px [radius] — Controls: md/lg; cards: xl; sheets: 2xl; status: pill.
- --cora-radius-lg: 12px [radius] — Controls: md/lg; cards: xl; sheets: 2xl; status: pill.
- --cora-radius-xl: 16px [radius] — Controls: md/lg; cards: xl; sheets: 2xl; status: pill.
- --cora-radius-2xl: 24px [radius] — Controls: md/lg; cards: xl; sheets: 2xl; status: pill.
- --cora-radius-pill: 9999px [radius] — Controls: md/lg; cards: xl; sheets: 2xl; status: pill.
- --cora-shadow-sm: 0 1px 2px rgba(0,0,0,0.05) [elevation] — Subtle surface lift.
- --cora-shadow-sheet: 0 20px 50px rgba(0,0,0,0.12) [elevation] — Overlay elevation; do not apply to every card.
- --cora-backdrop: rgba(9,9,11,0.45) [elevation] — Recommended modal backdrop, verify module behavior before replacing legacy overrides.
- --cora-duration-fast: 150ms [motion] — Hover and focus feedback.
- --cora-duration-normal: 200ms [motion] — Small transitions; no artificial wait.
- --cora-duration-sheet: 250ms [motion] — Sheet movement; disable for reduced motion.
- --cora-ease: cubic-bezier(0.2, 0, 0, 1) [motion] — Calm deceleration.
- --cora-content-marketing: 1240px [layout] — Current main marketing container, observed across shipped components.
- --cora-content-editorial: 1100px [layout] — Current editorial and business-tool shell width.
- --cora-content-docs: 1440px [layout] — Current documentation shell width.
- --cora-content-workspace: 1280px [layout] — Operational content maximum from legacy token specification.
- --cora-content-reading: 720px [layout] — Recommended long-form prose width.
- --cora-control-height: 44px [layout] — Recommended minimum interactive target.
- --cora-drawer-width: 448px [layout] — Desktop panels only; mobile uses bottom sheet.
- --cora-z-menu: 40 [layer] — Local menus within the feature stacking context.
- --cora-z-backdrop: 50 [layer] — Local overlay backdrop.
- --cora-z-sheet: 60 [layer] — Local sheet/dialog.
- --cora-z-toast: 70 [layer] — Local feedback above sheets; bridge existing global z-index carefully.

## Theme mappings
### light
- --cora-canvas: #ffffff
- --cora-bg: #ffffff
- --cora-surface: #fafafa
- --cora-selected: #f4f4f5
- --cora-border: #e4e4e7
- --cora-border-strong: #71717a
- --cora-text: #09090b
- --cora-muted: #52525b
- --cora-subtle: #71717a
- --cora-action: #09090b
- --cora-on-action: #ffffff
- --cora-action-hover: #27272a
- --cora-focus: #52525b
- --cora-success: #166534
- --cora-success-bg: #f0fdf4
- --cora-warning: #854d0e
- --cora-warning-bg: #fefce8
- --cora-danger: #b91c1c
- --cora-danger-bg: #fef2f2

### dark
- --cora-canvas: #09090b
- --cora-bg: #09090b
- --cora-surface: #18181b
- --cora-selected: #27272a
- --cora-border: #27272a
- --cora-border-strong: #71717a
- --cora-text: #fafafa
- --cora-muted: #d4d4d8
- --cora-subtle: #a1a1aa
- --cora-action: #fafafa
- --cora-on-action: #09090b
- --cora-action-hover: #e4e4e7
- --cora-focus: #a1a1aa
- --cora-success: #86efac
- --cora-success-bg: #14532d
- --cora-warning: #fde047
- --cora-warning-bg: #422006
- --cora-danger: #fca5a5
- --cora-danger-bg: #450a0a

## Typography
- Display: --cora-text-display; weight 600–700; line-height 1.1; tracking -0.025em; Marketing hero; clamp to 32px on mobile; existing campaigns may use larger type.
- Page title: --cora-text-h1; weight 600–700; line-height 1.2; tracking -0.02em; One h1 per page; operational headings may use 24px.
- Section title: --cora-text-h2; weight 600; line-height 1.3; tracking -0.015em; Sections / sheet headings, semantic h2.
- Card title: --cora-text-h3; weight 600; line-height 1.4; tracking -0.01em; Grouped content and card headings.
- Body: --cora-text-body; weight 400; line-height 1.6; tracking -0.011em; Reading, forms on mobile; product dense rows use small (14px).
- Small: --cora-text-small; weight 400–500; line-height 1.5; tracking 0; Supporting copy and product rows.
- Caption: --cora-text-caption; weight 400–500; line-height 1.4; tracking 0; Metadata; never essential input copy below 12px.
- Code: --cora-text-code; weight 400–500; line-height 1.6; tracking 0; Copyable code; horizontal scrolling confined to its own block.

## Component contracts
### button: Button
Level: Atom
Status: implemented
Implementation: components/design-system/primitives.tsx → Button
States: default, hover, focus-visible, disabled, loading
- Primary: solid monochrome; secondary: soft border; ghost: tonal hover; danger: text plus semantic surface.
- 44px minimum target; native button semantics; type=button unless submit is intentional.
- Loading retains its label, disables repeat submissions and exposes aria-busy. Icon-only buttons need an accessible name.

### input: Text field
Level: Atom
Status: implemented
Implementation: components/design-system/primitives.tsx → TextField
States: default, focus-visible, disabled, error, required
- Visible associated label, stable id, hint and error via aria-describedby.
- Error uses aria-invalid and explanatory text. Do not use placeholder as label.
- Mobile input text is 16px. Choose autocomplete, type and inputMode for the task.

### badge: Status badge
Level: Atom
Status: implemented
Implementation: components/design-system/primitives.tsx → Badge
States: neutral, success, warning, danger
- Neutral is the default. Success, warning and danger only communicate state.
- Include human-readable status; never rely on a colored dot alone.

### card: Surface card
Level: Atom
Status: implemented
Implementation: components/design-system/primitives.tsx → Card
States: default, selected (when selectable), empty
- Subtle one-pixel border, 16px radius, 24px padding.
- A card is not clickable by default; put an explicit link or action inside.

### icons: Iconography
Level: Foundation
Status: existing-pattern
Implementation: lucide-react in marketing / existing SVG product icons
States: decorative, labelled
- Use SVG icons, typically 16/20/24px, consistent 1.8–2.2px stroke.
- Decorative icons aria-hidden; icon actions need text equivalents. No emoji substitutions.

### selection: Checkbox / radio / switch
Level: Atom
Status: existing-pattern
Implementation: Existing feature controls; prefer native inputs
States: unchecked, checked, focus, disabled
- Label the input; preserve checked, disabled and keyboard behavior.
- Use tonal filled selection and a check indicator; no heavy dark card border.

### tabs: Tabs / segmented control
Level: Molecule
Status: existing-pattern
Implementation: Feature-local; no shared tab primitive yet
States: selected, unselected, keyboard focus
- Use tabs only for same-page panels; use anchors for route navigation.
- ARIA tablist/tab/tabpanel, selected state, roving focus and arrow keys required for custom tabs. Native radios are valid for settings.

### select: Select / combobox
Level: Atom
Status: existing-pattern
Implementation: Native select preferred; feature-local custom menus
States: closed, open, selected, empty, disabled
- Use native select for short lists. Custom searchable controls need full combobox keyboard behavior.
- Mobile filters may open a bottom sheet. Maintain a visible label.

### toast: Toast notification
Level: Molecule
Status: existing-pattern
Implementation: Marketing: components/ui/Toast.tsx; workspace: window.coraShowToast
States: info, success, error, dismissed
- Reuse the host notification API. No native alert, confirm or prompt.
- Informational messages use role=status, urgent errors role=alert; actionable messages need a dismiss option.
- Existing placement differs: marketing bottom center, workspace mobile top center / desktop bottom right. Do not create a third toast stack.

### sheet: Sheet / dialog
Level: Organism
Status: implemented
Implementation: components/design-system/primitives.tsx → Sheet; existing feature-local panels remain separate
States: closed, open, submitting, validation error, unsaved
- Shared primitive: native dialog with modal focus containment, background inertness, Escape dismissal and focus return.
- placement=sheet (default) preserves centred desktop geometry and bottom-sheet geometry at <=767px. placement=drawer is a right-edge full-height panel at >=1024px and a bottom sheet below 1024px. placement=modal remains centred at all widths.
- Bottom sheets use a drag handle, 24px top corners, explicit close and safe-area inset. The handle is a visual affordance; dismiss with Close or Escape. All placements are modal; modeless inspectors retain their existing feature-local behavior.
- Title is associated through aria-labelledby; protect unsaved work in the caller. Verify module backdrops before migration.

### table: Data table
Level: Organism
Status: existing-pattern
Implementation: Workspace feature views / semantic HTML tables
States: loading, populated, empty, filtered empty, error, selected
- Keep table headers, caption or accessible name and tabular numbers.
- At narrow widths use labelled cards or a local scroll container; never clip actions.
- Filters, sortable headers and pagination retain keyboard access and show empty/error states.

### kanban: Kanban board
Level: Organism
Status: existing-pattern
Implementation: Workspace CRM / lead views
States: empty stage, dragging, moved, save failure
- Stages retain industry-aware labels. Provide non-drag move controls for keyboard and touch.
- Confine horizontal board scroll; show stage counts and clear drop feedback.

### stepper: Guided workflow
Level: Molecule
Status: existing-pattern
Implementation: Document creation and signature flows
States: current, completed, upcoming, blocked
- Existing contract sequence: Details → Terms → GST Math → E-Sign → Complete.
- Use aria-current=step, validate before advancing, preserve entered values when going back.
- On mobile show current step and progress without tiny overflowing labels.

### upload: File upload
Level: Molecule
Status: existing-pattern
Implementation: Media / vault / tools views
States: idle, drag-over, uploading, complete, rejected
- A dropzone includes a real labelled file input and keyboard alternative.
- Show accepted types, size limit, progress, cancel, failure and retry. Never promise privacy beyond actual processing.

### dates: Date / schedule controls
Level: Molecule
Status: existing-pattern
Implementation: Crew scheduler and booking views
States: available, selected, unavailable, invalid
- Display timezone and local format explicitly. Native controls are preferred where practical.
- Calendar grids need keyboard navigation, selected date labels and unavailable state.

### empty: Empty / error / skeleton
Level: Molecule
Status: existing-pattern
Implementation: Feature-local states
States: loading, empty, error, retry
- Distinguish no records, no filter matches, denied access and failed fetch.
- Give one meaningful next action; use aria-busy for loading regions.
- No artificial delays. Skeleton geometry matches final content; respect reduced motion.

### navigation: Navigation shell
Level: Organism
Status: existing-pattern
Implementation: Marketing Navbar/Footer; workspace header/sidebar
States: current, collapsed, expanded, mobile
- Reuse the current shell and route-aware active states.
- Workspace admin widget stays anchored at sidebar bottom with a profile popover.
- Mobile navigation uses vertical sheet or in-flow menu; headings and skip links support keyboard navigation.

### search: Search / filters
Level: Molecule
Status: existing-pattern
Implementation: Docs, tools and feature catalogs
States: idle, results, no results, cleared
- Visible label, clear query, result count and useful no-results state.
- Filters preserve query and communicate active state; URL state when sharable.

### tooltip: Tooltip / popover
Level: Molecule
Status: existing-pattern
Implementation: Feature-local contextual help
States: closed, open, dismissed
- Help must be available on keyboard focus and touch, not hover alone.
- Critical instructions belong in visible copy. Escape dismisses, focus remains stable.

### hero: Marketing hero
Level: Organism
Status: existing-pattern
Implementation: components/hero/Hero.tsx and page-specific heroes
States: desktop, mobile, reduced motion
- One clear page promise, supporting copy and primary action.
- Retain established artwork; stack copy and illustration on mobile.
- Decorative imagery has empty alt text; informative imagery needs meaningful alt.

### feature-grid: Feature / industry grid
Level: Organism
Status: existing-pattern
Implementation: components/features and components/industry
States: all, filtered, empty, detail
- Reuse domain data registry and existing card components.
- One column on phone, two on tablet, three where readable; maintain heading order.

### pricing: Pricing / checkout
Level: Organism
Status: existing-pattern
Implementation: components/pricing/PricingSection.tsx and CheckoutSheet.tsx
States: plan selected, billing switched, processing, failed, complete
- Explain currency, billing period and limits in visible text.
- Primary action remains monochrome; selected plan is tonal.
- Payment sheets preserve loading/error states and mobile close behavior.

### editorial: Docs / articles / guides
Level: Organism
Status: existing-pattern
Implementation: components/docs, components/blog, components/guides
States: reading, TOC open, searching
- Readable prose column, heading anchors, code overflow contained, mobile TOC.
- Preserve current content schemas; provenance and updated dates remain visible.

### tool: Micro-tool shell
Level: Organism
Status: existing-pattern
Implementation: components/tools/ToolPageShell.tsx; components/tools/framework/ToolContainer.tsx
States: initial, valid result, invalid input, reset, export
- Use the established shell for the tool family. Existing families differ; do not combine randomly.
- Label every numeric input; show units, assumptions, rounding and result interpretation.
- Primary calculation remains usable on mobile with output directly after input.

### ai: AI input / execution feedback
Level: Organism
Status: existing-pattern
Implementation: components/hero/HeroAIInput.tsx and feature-local agent panels
States: idle, composing, processing, result, failure
- Explain what an action will do, show processing state and allow cancellation when supported.
- Never show simulated execution as a completed real action; expose recoverable errors.
- Model and quota labels come from active configuration, not hardcoded historical models.

## Visual catalog
Each specimen links to existing component contracts by componentIds. Reuse the shared primitive API when status is shared-primitive. A reference-recipe demonstrates a composition, not a new shared component API or evidence of a completed legacy migration.

Examples are structural JSX fragments. Import Button, TextField, Card, Badge and Sheet from @/components/design-system/primitives when used. Caller variables and handlers are illustrative and must be implemented. Adapt behavior from the preview source and feature context; use semantic tokens for the feature stylesheet and verify its complete state matrix.

Catalog source paths resolve from the repository root. An existing pattern source establishes context; its legacy styles are not approved values to copy. Public samples use fictional records. File previews remain local demonstrations and do not perform an upload, payment, publication or destructive operation.

The catalog lives on the existing /design-system route. JSON and plain text include the same records and version. Publish with the existing marketing site release; do not create a second project or duplicate registry.

Renderer: cora-frontend/components/design-system/VisualCatalog.tsx
Preview implementation: cora-frontend/components/design-system/CatalogPreviews.tsx

### surface-card: Surface card
Category: cards
Status: shared-primitive
The neutral container for related information, with clear hierarchy and an explicit inner action.
Component contracts: card, badge
Pattern source: cora-frontend/components/design-system/primitives.tsx
Variants: standard surface, tonal selection, compact content
State requirements: default, selected, empty, focus on inner action
Usage:
- Use Card as the common surface instead of redefining border, radius and padding.
- Selection belongs to a labelled control and tonal fill. A div card is not a button.
- Keep titles, supporting text and metadata in that order; use a link for navigation.
Structural example (implement caller state and handlers):
```tsx
<Card><Badge>Draft</Badge><h3>Project overview</h3><p>Prepare the next delivery.</p><a href="/features/">View features</a></Card>
```

### feature-card: Feature card
Category: cards
Status: reference-recipe
An icon, one concrete capability and supporting copy for a marketing feature or industry grid.
Component contracts: card, feature-grid, icons
Pattern source: cora-frontend/components/features/FeatureCards.tsx
Variants: icon and copy, capability list, visual feature
State requirements: default, link hover, focus-visible, grid stacked
Usage:
- Reuse the feature data registry and existing feature shell; preserve heading order.
- Use a neutral icon tile for interface examples. Authentic brand artwork keeps its content colors.
- Use one column on phones; add columns only while copy remains readable. Legacy colors in the source require scoped migration.
Structural example (implement caller state and handlers):
```tsx
<Card><h3>Projects in one place</h3><p>Keep milestones, files and decisions together.</p><a href="/features/">Explore features</a></Card>
```

### project-card: Project card
Category: cards
Status: reference-recipe
A workspace record with status, sample owner, due date, progress and an explicit details action.
Component contracts: card, badge, button
Pattern source: app/public/wp-content/plugins/cora-workspace/views/view-projects.php
Variants: active project, completed project, selected record
State requirements: default, selected, loading, empty, permission restricted
Usage:
- Keep selected-record context while opening details. Do not make a card with nested buttons a single clickable target.
- Name progress with visible text and a labelled progress element; include the due date format.
- Public examples use fictional owners. Actual industry terminology and permissions come from the host configuration.
Structural example (implement caller state and handlers):
```tsx
<Card><Badge tone="success">Active</Badge><h3>Studio refresh</h3><p>4 of 6 milestones complete</p><progress aria-label="Milestone completion" value={4} max={6} /><Button variant="secondary" onClick={openDetails}>View project</Button></Card>
```

### metric-card: Metric card
Category: cards
Status: reference-recipe
A labelled operational value with units, comparison period and an explanation of change.
Component contracts: card, badge, table
Pattern source: app/public/wp-content/plugins/cora-workspace/views/view-financials.php
Variants: count, currency, comparison
State requirements: populated, loading, no data, unavailable
Usage:
- Use tabular numbers and show currency or unit in visible copy.
- Explain the comparison period and direction in text. A green number alone does not establish an improvement.
- Never show unavailable data as zero; distinguish loading, no activity and fetch failure.
Structural example (implement caller state and handlers):
```tsx
<Card><h3>Invoices paid</h3><p>₹48,000</p><p>Sample month · INR</p><Badge tone="success">Up 8% from the previous month</Badge></Card>
```

### pricing-card: Pricing card
Category: cards
Status: reference-recipe
A sample plan with price, billing period, limits and a clear selection action.
Component contracts: card, pricing, button, selection
Pattern source: cora-frontend/components/pricing/PricingSection.tsx
Variants: monthly, annual, selected plan
State requirements: default, selected, billing switched, processing, failed
Usage:
- Catalog prices are fictional examples, never a replacement for active commercial plan configuration.
- Display currency, billing period, tax treatment and limits before the action.
- Selected plans use tonal fills and text indicators. Checkout uses the existing host flow.
Structural example (implement caller state and handlers):
```tsx
<Card><h3>Sample plan</h3><p>₹999 / month · sample price</p><ul><li>5 sample projects</li></ul><Button onClick={selectPlan}>Choose sample plan</Button></Card>
```

### blog-card: Blog and article card
Category: cards
Status: reference-recipe
An editorial cover, topic, title, excerpt and reading metadata for a discoverable article.
Component contracts: card, editorial, icons
Pattern source: cora-frontend/components/blog/BlogArticleCard.tsx
Variants: article card, featured article, related guide
State requirements: default, image loading, image unavailable, link focus
Usage:
- Use the existing blog article schema and valid route. Keep published or updated dates accurate.
- Use a 16:9 cover and meaningful alt text when it communicates article content; decorative covers use empty alt.
- Prevent repeated links with ambiguous accessible names. This recipe documents structure while legacy editorial styles remain audited separately.
Structural example (implement caller state and handlers):
```tsx
<Card><article><p>Guides · 5 min read</p><h3><a href="/blog/">Planning a calmer workflow</a></h3><p>A sample article about keeping decisions visible.</p><p>Updated 13 October 2026</p></article></Card>
```

### button-matrix: Buttons and actions
Category: controls
Status: shared-primitive
Primary, secondary, ghost and destructive actions with loading, disabled and icon-label examples.
Component contracts: button, icons
Pattern source: cora-frontend/components/design-system/primitives.tsx
Variants: primary, secondary, ghost, danger, icon with label
State requirements: default, hover, focus-visible, disabled, loading
Usage:
- Use Button for actions and an anchor for navigation. Preserve the 44px target.
- Loading disables repeated clicks while retaining a human-readable label and aria-busy.
- Icon-only actions require an accessible name; decorative icons are hidden from assistive technology.
Structural example (implement caller state and handlers):
```tsx
<><Button onClick={save}>Save changes</Button><Button variant="secondary">Cancel</Button><Button variant="ghost">More options</Button><Button variant="danger">Remove sample</Button><Button loading>Saving changes</Button><Button disabled>Unavailable</Button></>
```

### form-fields: Form fields and validation
Category: controls
Status: shared-primitive
Visible labels, supporting hints, required inputs, disabled controls and actionable field errors.
Component contracts: input, select, button
Pattern source: cora-frontend/components/design-system/primitives.tsx
Variants: text, email, hint, required, error, disabled
State requirements: empty, entered, focus-visible, invalid, disabled
Usage:
- Use TextField so labels and description IDs stay associated. Placeholder text is never the label.
- Choose input type, autocomplete and inputMode for the actual task; retain 16px text on mobile.
- Preserve entered values on validation failure, identify the field and explain the correction.
Structural example (implement caller state and handlers):
```tsx
<><TextField label="Project name" hint="Visible to your team" required /><TextField label="Email address" type="email" autoComplete="email" error="Enter a complete email address." /><TextField label="Reference" value="Assigned after creation" disabled /></>
```

### selection-controls: Checkboxes, radios and switches
Category: controls
Status: reference-recipe
Native labelled selection for independent choices, exclusive options and a binary preference.
Component contracts: selection, select
Pattern source: cora-frontend/components/design-system/CatalogPreviews.tsx
Variants: checkbox, radio group, switch, native select
State requirements: unchecked, checked, focus-visible, disabled
Usage:
- Use native input behavior with visible labels and a fieldset legend for grouped choices.
- Radio options in one group share a name. A switch exposes its checked state and a stable label.
- Use tonal selection plus an indicator; do not introduce a heavy selected card outline.
Structural example (implement caller state and handlers):
```tsx
<fieldset><legend>Delivery preference</legend><label><input type="radio" name="delivery" value="email" defaultChecked /> Email</label><label><input type="radio" name="delivery" value="portal" /> Client portal</label><label><input type="checkbox" /> Include a summary</label></fieldset>
```

### navigation-tabs: Tabs and segmented navigation
Category: controls
Status: reference-recipe
Same-page panels with selected state, matching panel relationships and keyboard navigation.
Component contracts: tabs, navigation
Pattern source: cora-frontend/components/design-system/CatalogPreviews.tsx
Variants: panel tabs, segmented options
State requirements: selected, unselected, keyboard focus, panel visible
Usage:
- Use anchors for route navigation; tabs select same-page panels.
- Implement roving tabindex, Arrow keys, Home and End with tablist/tab/tabpanel relationships.
- Keep the active state tonal and readable. Use native radios when selecting a setting instead of switching content.
Structural example (implement caller state and handlers):
```tsx
<><div role="tablist" aria-label="Project views"><button role="tab" id="overview-tab" aria-controls="overview-panel" aria-selected={true}>Overview</button></div><section role="tabpanel" id="overview-panel" aria-labelledby="overview-tab">Project overview</section></>
```

### search-filter: Search and filters
Category: controls
Status: reference-recipe
A labelled query with clear action, result count and an explicit no-results response.
Component contracts: search, input, select, button
Pattern source: cora-frontend/components/blog/BlogSearch.tsx
Variants: search input, category filter, clear query
State requirements: idle, results, no results, cleared
Usage:
- Name the collection being searched and announce changing result counts without moving focus.
- Retain query when changing filters; use URL state for shareable views.
- No results should offer Clear filters and distinguish absence from a service error.
Structural example (implement caller state and handlers):
```tsx
<><TextField label="Search projects" type="search" value={query} onChange={e => setQuery(e.target.value)} /><Button variant="ghost" onClick={() => setQuery('')}>Clear search</Button><p role="status">{results.length} sample results</p></>
```

### modal-dialog: Modal dialog
Category: overlays
Status: shared-primitive
A focused task with a labelled title, contained keyboard focus and explicit completion or cancellation.
Component contracts: sheet, input, button
Pattern source: cora-frontend/components/design-system/primitives.tsx
Variants: centred modal, narrow-screen modal
State requirements: closed, open, submitting, validation error, dismissed
Usage:
- Reuse Sheet with placement=modal for a centred dialog at every width. The native dialog supplies background inertness and focus containment.
- Escape and an explicit close action dismiss; return focus to the trigger.
- Keep one clear task per modal and protect unsaved work in caller state. Use placement=sheet or drawer when mobile bottom-sheet geometry is appropriate.
Structural example (implement caller state and handlers):
```tsx
<Sheet open={isOpen} onClose={() => setIsOpen(false)} placement="modal" title="Create sample project" footer={<Button onClick={createSample}>Create project</Button>}><TextField label="Project name" required /></Sheet>
```

### responsive-drawer: Drawer and mobile bottom sheet
Category: overlays
Status: shared-primitive
A contextual inspector positioned at the desktop edge and at the bottom of a narrow screen.
Component contracts: sheet, card, button
Pattern source: cora-frontend/components/design-system/primitives.tsx
Variants: desktop side inspector, mobile bottom sheet
State requirements: closed, open, detail selected, unsaved, dismissed
Usage:
- Use Sheet placement=drawer for a full-height right-edge modal panel at >=1024px and a vertical bottom sheet below 1024px.
- Preserve whether an existing feature inspector is modal or modeless. Do not silently replace a modeless inspector with this modal primitive.
- The primitive supplies an associated title, explicit Close, Escape, focus containment/return and local scroll containment. Caller state preserves the selected record and protects unsaved changes.
Structural example (implement caller state and handlers):
```tsx
<Sheet open={isOpen} onClose={() => setIsOpen(false)} placement="drawer" title="Project details"><p>Selected sample project</p></Sheet>
```

### confirmation-dialog: Destructive confirmation
Category: overlays
Status: reference-recipe
A custom confirmation that identifies the affected sample record and the consequence of proceeding.
Component contracts: sheet, button
Pattern source: cora-frontend/components/design-system/CatalogPreviews.tsx
Variants: remove record, discard changes
State requirements: closed, open, cancelled, confirming, failed
Usage:
- Use Sheet with clear consequence copy; never browser-native confirm or alert.
- Offer a visible Cancel and a specifically labelled destructive action. Do not use an ambiguous Yes.
- Preview confirmation updates fictional local state only. Production removal needs permission, pending state and recoverable failure.
Structural example (implement caller state and handlers):
```tsx
<Sheet open={isConfirming} onClose={cancelRemoval} title="Remove sample project?" footer={<><Button variant="secondary" onClick={cancelRemoval}>Cancel</Button><Button variant="danger" onClick={removeSample}>Remove sample project</Button></>}><p>The sample will disappear from this preview.</p></Sheet>
```

### toast-feedback: Toast and inline feedback
Category: overlays
Status: reference-recipe
Status messages that announce a local outcome and offer an explicit dismissal or recovery action.
Component contracts: toast, badge, button
Pattern source: cora-frontend/components/design-system/CatalogPreviews.tsx
Variants: informational, success, error, dismissible
State requirements: idle, visible, dismissed, retry available
Usage:
- Use the host notification API in real features. This inline reference does not create another global toast stack.
- Use role=status for informational feedback and role=alert for urgent errors; do not move focus to routine messages.
- Include text and a recovery action for failure; avoid relying on color or vanishing error messages.
Structural example (implement caller state and handlers):
```tsx
<div role="status"><p>Sample changes saved.</p><Button variant="ghost" onClick={dismissMessage} aria-label="Dismiss saved message">Dismiss</Button></div>
```

### accordion: Accordion and disclosure
Category: content
Status: reference-recipe
Optional supporting information revealed through a named disclosure control.
Component contracts: editorial, button
Pattern source: cora-frontend/components/blog/BlogFAQAccordion.tsx
Variants: single disclosure, FAQ group
State requirements: collapsed, expanded, keyboard focus
Usage:
- Prefer native details/summary when it suits the content; it supplies keyboard disclosure behavior.
- Critical instructions and validation stay visible outside a collapsed disclosure.
- For custom disclosure buttons associate aria-expanded and aria-controls; keep hidden content out of tab order.
Structural example (implement caller state and handlers):
```tsx
<details><summary>How are project states used?</summary><p>Draft is editable; Ready for review awaits a decision; Complete records the final outcome.</p></details>
```

### editorial-text: Typography and editorial structure
Category: content
Status: reference-recipe
Readable headings, paragraph text, lists, quote, links and code inside a contained reading column.
Component contracts: editorial, hero
Pattern source: cora-frontend/components/blog/BlogBlockRenderer.tsx
Variants: article prose, documentation, inline code, quote
State requirements: reading, link focus, code overflow contained
Usage:
- Preserve General Sans in marketing and Inter in workspace; use the contract type roles.
- Use sequential semantic headings and a reading width near --cora-content-reading. Long code scrolls locally.
- Quotes need source context; publishing and updated dates remain visible when available.
Structural example (implement caller state and handlers):
```tsx
<article><h2>Keep decisions visible</h2><p>A clear project record gives the team one place to find context.</p><ul><li>Define the outcome.</li><li>Assign the next action.</li></ul><blockquote><p>Write the decision beside the work.</p></blockquote><p>Use <code>--cora-text-body</code> for reading copy.</p></article>
```

### empty-loading: Empty, loading and error states
Category: content
Status: reference-recipe
Distinct treatments for a new collection, no filter matches, loading and a failed request.
Component contracts: empty, button, card
Pattern source: cora-frontend/components/design-system/CatalogPreviews.tsx
Variants: first use, filtered empty, loading skeleton, recoverable error
State requirements: loading, empty, error, retry, populated
Usage:
- First use offers one meaningful creation action; filtered empty offers Clear filters.
- Use aria-busy on the loading region and a short status label; skeleton geometry matches the eventual content.
- Failed requests show a recoverable explanation and Retry. Never simulate a successful service response.
Structural example (implement caller state and handlers):
```tsx
<Card><h3>No projects yet</h3><p>Create a project to keep the next delivery organised.</p><Button onClick={openCreate}>Create sample project</Button></Card>
```

### data-table: Data table
Category: data
Status: reference-recipe
A semantic sample records table with clear column headers, statuses and explicit row actions.
Component contracts: table, badge, button
Pattern source: app/public/wp-content/plugins/cora-workspace/views/view-leads.php
Variants: records table, filtered table, mobile contained scroll
State requirements: populated, loading, empty, filtered empty, error, row action focus
Usage:
- Keep table caption, scope=col headers and text status labels; numeric data uses tabular figures.
- On mobile keep wide tables inside a named local scroll region or provide labelled cards. Page overflow is forbidden.
- Sorting, filters and pagination must remain keyboard accessible and reflect visible result counts.
Structural example (implement caller state and handlers):
```tsx
<table><caption>Sample projects</caption><thead><tr><th scope="col">Project</th><th scope="col">Status</th></tr></thead><tbody><tr><th scope="row">Studio refresh</th><td><Badge tone="success">Active</Badge></td></tr></tbody></table>
```

### kanban-board: Kanban board
Category: data
Status: reference-recipe
A stage-based sample board with counts and a non-drag way to move records.
Component contracts: kanban, card, select
Pattern source: app/public/wp-content/plugins/cora-workspace/views/view-leads.php
Variants: stage columns, empty stage, keyboard move
State requirements: populated, empty stage, moving, moved, save failure
Usage:
- Resolve stage names from the active industry. Catalog stage labels are illustrative.
- Provide a labelled move select or buttons for keyboard and touch; drag is optional.
- Announce the new stage and preserve context. Constrain horizontal board scrolling to its region.
Structural example (implement caller state and handlers):
```tsx
<section aria-label="Sample pipeline"><h3>In progress · 1</h3><Card><h4>Studio refresh</h4><label>Move sample to<select value={stage} onChange={e => moveSample(e.target.value)}><option>Planned</option><option>In progress</option><option>Complete</option></select></label></Card></section>
```

### workflow-stepper: Workflow stepper
Category: data
Status: reference-recipe
A guided workflow showing completed, current and upcoming steps with reachable next/back actions.
Component contracts: stepper, button, input
Pattern source: app/public/wp-content/plugins/cora-workspace/views/view-vault.php
Variants: full sequence, mobile current step, blocked progression
State requirements: current, completed, upcoming, blocked
Usage:
- Use the documented document flow when building documents: Details → Terms → GST Math → E-Sign → Complete.
- Set aria-current=step on the current item, validate before moving forward and preserve values when going back.
- At narrow widths keep a readable current-step label and avoid tiny overflowing labels.
Structural example (implement caller state and handlers):
```tsx
<nav aria-label="Document creation progress"><ol><li aria-current="step">Details</li><li>Terms</li><li>GST Math</li><li>E-Sign</li><li>Complete</li></ol></nav>
```

### image-treatment: Images and avatars
Category: media
Status: reference-recipe
Editorial 16:9, gallery 4:3 and square/avatar image frames with captions and fallback treatment.
Component contracts: hero, card, icons
Pattern source: app/public/wp-content/plugins/cora-workspace/views/view-media.php
Variants: 16:9 editorial cover, 4:3 gallery image, 1:1 square image, avatar and initials
State requirements: loaded, loading, unavailable, selected
Usage:
- Image content preserves its original colors; interface borders and surrounding controls use semantic tokens.
- Choose object-fit intentionally. Do not crop essential faces, document text or meaning; image captions retain attribution where needed.
- Informative images need meaningful alt; decorative images use empty alt. Avatar labels identify the fictional sample user and provide initials fallback.
Structural example (implement caller state and handlers):
```tsx
<figure><img src={sampleCoverSrc} alt="Illustrated sample project workspace" width={640} height={360} /><figcaption>Sample editorial cover · 16:9</figcaption></figure>
```

### file-upload: File upload
Category: media
Status: reference-recipe
A labelled real file control with limits, local validation and explicit file-selection feedback.
Component contracts: upload, input, button
Pattern source: cora-frontend/components/design-system/CatalogPreviews.tsx
Variants: file picker, dropzone, file summary, rejected file
State requirements: idle, selected, drag-over, uploading, complete, rejected
Usage:
- The catalog selection demo validates file metadata locally and does not send a file to a server.
- Show supported type and size limit in visible copy. Keep a keyboard-accessible real file input even if drag and drop is added.
- Production upload must implement progress, cancellation, server validation, failure and retry. Never claim a local selection is an upload success.
Structural example (implement caller state and handlers):
```tsx
<><label htmlFor="sample-file">Choose sample image</label><input id="sample-file" type="file" accept="image/png,image/jpeg" aria-describedby="sample-file-hint" onChange={validateSampleFile} /><p id="sample-file-hint">PNG or JPEG. Maximum 5 MB. Local preview only.</p></>
```

### icon-library: Icons and meaningful labels
Category: media
Status: reference-recipe
Consistent SVG glyphs for navigation, actions, files, media and status, paired with accessible names.
Component contracts: icons, button
Pattern source: cora-frontend/components/features/FeatureIcon.tsx
Variants: 16px inline, 20px control, 24px tile, icon with label, icon-only action
State requirements: decorative, labelled, focus-visible, disabled
Usage:
- Use lucide-react or existing product SVGs; typically 16/20/24px with 1.8–2.2px stroke. Do not substitute emojis.
- Keep decorative icons aria-hidden and name the containing action in human language.
- Icon-only buttons need aria-label or visible accessible text. Status icons still require a readable state label.
Structural example (implement caller state and handlers):
```tsx
<Button variant="secondary" aria-label="Open project files"><svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true"><path d="M3 7h6l2 2h10v11H3z" /></svg></Button>
```

## Responsive layout
- < 640px: Phone: one-column forms and cards, 16px outer gutter, 44px targets, 16px input text, bottom sheets; local table/code overflow only.
- 640–767px: Large phone / small tablet: grow gutters to 24px when space permits; do not assume desktop panel behavior.
- 768–1023px: Tablet: two-column content where readable. Existing workspace sheets use <=1023px; preserve the module breakpoint.
- >= 1024px: Desktop: persistent in-flow navigation, 24–32px gutters and content max width. Desktop panels only where the feature supports them.
- Zoom / safe area: Reflow at 320px and 200% zoom. Respect env(safe-area-inset-bottom). Never disable pinch zoom or hide essential overflow.

## Accessibility
- Normal text contrast at least 4.5:1; large text 3:1; necessary control boundaries / focus indicators 3:1. Verify each actual pairing, including dark mode.
- Keyboard focus must remain clearly visible. A subtle focus outline is required even though heavy decorative outlines are forbidden.
- Use semantic landmarks, sequential headings, associated labels, native controls and an accessible name for every icon action.
- Announce asynchronous status without moving focus. Errors identify the field and explain how to recover.
- Modal focus is contained and restored; Escape and an explicit close work. Never place hidden panels in the tab order.
- Respect prefers-reduced-motion, browser zoom and touch input. No automatic marquee or smooth scrolling for reduced-motion users.
- Status is conveyed by label or icon plus color. Do not use muted opacity for essential text.

## Content and terminology
- Use clear task language: Save changes, Create invoice, Move lead. Avoid technical infrastructure terms in customer workflows.
- Use fictional sample identities and no real owner or customer data in public UI or fixtures.
- Workspace labels resolve from active industry: equipment/property listings, shoots/showings, client/buyer leads. Do not hardcode industry names in shared views.
- Show currency, tax assumptions, dates and timezone explicitly. Keep identifiers and financial numbers tabular.
- Destructive actions explain the affected record and recovery limits; use custom confirmation surfaces.

## Audit and migration register
### D01: Legacy token files (migration-required)
Observed: Root cora-design-tokens.js and frontend lib/cora-tokens.ts duplicate values and are not the executable source for current styling.
Decision: Historical references only. New UI consumes this contract and primitives; migrate a feature when touching it.
Sources: cora-design-tokens.js; cora-frontend/lib/cora-tokens.ts; cora-design-system.html

### D02: Typography (documented-exception)
Observed: Old tokens and brand page specify Inter; marketing runtime loads General Sans.
Decision: Preserve General Sans on marketing and Inter in workspace. Reconcile brand documentation in a separate scoped edit.
Sources: cora-frontend/styles/globals.css; cora-frontend/components/brand/BrandTypographySection.tsx

### D03: Color (migration-required)
Observed: Legacy WordPress Tailwind palette includes gold/bronze; status shades differ between brand and token files.
Decision: Zinc remains the inherited UI baseline. New status text tokens use darker legible colors; no gold action theme.
Sources: app/public/wp-content/plugins/cora-workspace/tailwind.config.js; cora-frontend/components/brand/BrandColorsSection.tsx

### D04: Mobile panels (migration-required)
Observed: Legacy tokens permit sliding drawers; workspace instructions require bottom sheets. CSS has overlapping 641px/1023px panel ranges.
Decision: Mobile vertical sheets take precedence. Audit the feature breakpoint and focus behavior before modifying a legacy panel.
Sources: .agents/AGENTS.md; app/public/wp-content/plugins/cora-workspace/assets/css/admin-style.css

### D05: Overlay backdrop (documented-exception)
Observed: Workspace guidance calls for blurred dark backdrop; some runtime CSS makes backdrops transparent.
Decision: The dark backdrop token is recommended for new modal patterns. Preserve and investigate existing module overrides when migrating.
Sources: app/public/wp-content/plugins/cora-workspace/assets/css/admin-style.css

### D06: Feedback (documented-exception)
Observed: Marketing and workspace toast locations and z-index stacks differ.
Decision: Reuse host API and placement. The local layer scale applies to new isolated components, not a global z-index rewrite.
Sources: cora-frontend/components/ui/Toast.tsx; app/public/wp-content/plugins/cora-workspace/assets/js/admin-script.js

### D07: Accessibility (migration-required)
Observed: Existing outline bans and animations can conflict with keyboard focus and reduced-motion needs.
Decision: Visible focus and reduced motion take precedence. New primitives implement focus and motion behavior; audit existing features on touch.
Sources: .agents/AGENTS.md; cora-frontend/components/providers/SmoothScrollProvider.tsx

## Verification
- Source contract and all machine exports stay synchronized.
- No undocumented color/font literals in new design-system UI.
- Button loading, field errors, theme contrast and search work with keyboard.
- Inspect 390px and 1440px layouts and ensure no page-level horizontal overflow.
- Confirm /docs, /tools and marketing homepage still render with unchanged host styles.
- Build static export and confirm manifest.json, llms.txt and tokens.css exist in out/design-system.