Explore the cards, controls, overlays and content behind Cora. Try real examples, inspect their structure, and build from the same versioned contract as our coding agents.
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.
cora-frontend/lib/design-system.ts
Inherited design direction is preserved. Newly formalized tokens and accessible primitives are recommendations for future work; known legacy differences are recorded below. Updated 2026-10-13.
01 / REFERENCE
The visual catalog
An organized library of interactive specimens. Inspect the details, change the surface and theme, and carry each pattern into the next feature.
For people
Browse a category, try the controls, and expand an example. Open “Usage & code” for variants, required states, and its source.
For developers & agents
Reuse shared primitives. Adapt reference recipes to the feature, then verify every required state. Read the JSON manifest or agent contract before implementation.
24 of 24 specimens · Interactive examples use fictional data.
Cards
Surface card
Shared primitive
The neutral container for related information, with clear hierarchy and an explicit inner action.
A quiet, useful surface.
Default
Cards group related content with a clear heading, useful context, and one primary next action.
Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Controls
Buttons and actions
Shared primitive
Primary, secondary, ghost and destructive actions with loading, disabled and icon-label examples.
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.
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.
Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Content
Typography and editorial structure
Reference recipe
Readable headings, paragraph text, lists, quote, links and code inside a contained reading column.
Studio journal · Example typography
Good work needs a little breathing room.
A thoughtful workspace makes the next step clear and gives the important things room to stand out.
Design team13 October 20264 min read
Start with a shared rhythm.
Use headings to guide the reader, concise paragraphs to explain the idea, and consistent spacing to connect related details. Keep operational labels direct.
Clarity is a feature. Every action should have a name, a purpose, and useful feedback.
Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Content
Empty, loading and error states
Reference recipe
Distinct treatments for a new collection, no filter matches, loading and a failed request.
Your next project starts here.
Create a project to keep your team and ideas together.
Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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 & workflows
Data table
Reference recipe
A semantic sample records table with clear column headers, statuses and explicit row actions.
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.
Variants
16:9 editorial cover4:3 gallery image1:1 square imageavatar and initials
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.
A button or label for another product (WhatsApp, Google Meet, Gmail, Instagram…) shows that product’s official mark in full colour, not a line glyph (P07).
Variants
16px inline20px control24px tileicon with labelicon-only action
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.
02 / REFERENCE
Principles
The decisions that stay consistent across every feature.
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.
P07
Official marks for third-party services
Whenever the UI names or links to another product (WhatsApp, Gmail, Google, Google Meet / Calendar / Maps / Sheets / Docs / Slides / Drive, Business Profile, Meta, Instagram, Facebook, YouTube, LinkedIn, Razorpay, Stripe, Zoom, Slack, Shopify, WordPress, OpenAI, Claude, Gemini and the rest of the brand kit), draw its official mark in its official colours, never a generic glyph such as a chat bubble, map pin or external-link arrow. Workspace: V2.brand(key) / cora_v2_brand(key); V2.icon(key) and cora_v2_icon(key) return the mark automatically for brand keys. Use the one-colour variant (mono) only where the surface demands a single colour. Generic actions (email, call, link, copy) keep the line icons. A service missing from the kit is added to brands-data.php from its official source (simple-icons, CC0) before it ships.
03 / REFERENCE
Two surfaces. Shared semantics.
Choose a profile before writing UI. Preserve the type and canvas that actually ship.
existing-baselinemarketing
Marketing site
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.
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.
<Card><h3>Project summary</h3><p>Ready for review.</p></Card>
07 / REFERENCE
Component contracts
Implementation references, accepted states and interaction requirements. Five primitives are shared code; other records describe existing patterns to reuse and improve.
Atom
Button
Shared primitive
components/design-system/primitives.tsx → Button
Primary: solid monochrome; secondary: soft border; ghost: tonal hover; danger: text plus semantic surface.
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.
Statesinfosuccesserrordismissed
Organism
Sheet / dialog
Shared primitive
components/design-system/primitives.tsx → Sheet; existing feature-local panels remain separate
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.
Statesclosedopensubmittingvalidation errorunsaved
Organism
Data table
Existing pattern
Workspace feature views / semantic HTML tables
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.
A single readable workflow at every width. Existing feature breakpoints must be inspected before a panel is migrated.
< 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.
Mobile sheet anatomy
Sheet titleClose
Scrollable content Labels · inputs · validation
Sticky actions + safe area
Recommended modal pattern: up to 90dvh, 24px top corners, balanced scroll lock, focus containment and restoration. Modeless desktop inspectors retain their feature-local behavior.
10 / REFERENCE
Accessibility is part of the system
Calm visual design must remain perceivable, operable and understandable.
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.
11 / REFERENCE
Content & terminology
A consistent interface includes the words, sample identities and formats we use.
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.
12 / REFERENCE
Audit & migration register
Observed differences are explicit. Agents should resolve them within the feature they are changing.
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.
D01migration required
Legacy token files
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.
Keep the implementation and its public contract in the same change.
Read this manifest and the relevant profile before editing.
Inspect the existing feature, reuse its shell, and choose documented components.
Use named semantic tokens and reusable primitives; do not duplicate values.
If a new pattern is needed, update this source, component, states and rationale together.
Increment version: patch for corrections, minor for additive patterns, major for changed semantics.
Run check:design-system and build; inspect desktop, 390px mobile, keyboard and neighboring routes.
Document unresolved deviations; do not silently restyle unrelated modules.
Authority & approval
Inherited monochromatic design direction and existing executable product patterns. This release consolidates them; it does not claim every historical implementation is compliant.
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.
Current user instructions
Applicable repository instructions and accessibility requirements
This canonical contract and surface profile
Feature-local implementation and its documented exceptions
Legacy showcase and token files (historical only)
Definition of done
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.
cd cora-frontend
npm run check:design-system
npm run build
The automated guard checks the shared contract and design-system components. Legacy screens are migrated incrementally and require feature-specific verification.