Skip to design reference
coraDesign system
v1.1.0Documentation
CORA / DESIGN INFRASTRUCTUREPublic reference

A shared language.
For everything we build.

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.

Browse components JSON manifest Agent contract Token CSS
24Visual specimens
25Component contracts
82Named tokens
02Surface profiles

Start here, agent.

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.

Ready to add.

Permalink
Usage & code

When to use

  • 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.

Variants

standard surfacetonal selectioncompact content

Required states

defaultselectedemptyfocus on inner action

Source & contracts

cora-frontend/components/design-system/primitives.tsx
Surface cardStatus badge

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.tsx.

<Card><Badge>Draft</Badge><h3>Project overview</h3><p>Prepare the next delivery.</p><a href="/features/">View features</a></Card>
Cards

Feature card

Reference recipe

An icon, one concrete capability and supporting copy for a marketing feature or industry grid.

One place for the whole picture.

Bring your team, clients, and creative work together in one calm workspace.

WorkspaceCollaboration
Permalink
Usage & code

When to use

  • 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.

Variants

icon and copycapability listvisual feature

Required states

defaultlink hoverfocus-visiblegrid stacked

Source & contracts

cora-frontend/components/features/FeatureCards.tsx
Surface cardFeature / industry gridIconography

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.tsx.

<Card><h3>Projects in one place</h3><p>Keep milestones, files and decisions together.</p><a href="/features/">Explore features</a></Card>
Cards

Project card

Reference recipe

A workspace record with status, sample owner, due date, progress and an explicit details action.

In progress

Studio launch

Brand strategy, visual direction, and a thoughtful first impression.

18 Oct 20263 members

65% complete · Sample project

Permalink
Usage & code

When to use

  • 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.

Variants

active projectcompleted projectselected record

Required states

defaultselectedloadingemptypermission restricted

Source & contracts

app/public/wp-content/plugins/cora-workspace/views/view-projects.php
Surface cardStatus badgeButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Cards

Metric card

Reference recipe

A labelled operational value with units, comparison period and an explanation of change.

Projects this month
24
↑ 12%vs. previous month

Fictional data · Last 30 days

Permalink
Usage & code

When to use

  • 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.

Variants

countcurrencycomparison

Required states

populatedloadingno dataunavailable

Source & contracts

app/public/wp-content/plugins/cora-workspace/views/view-financials.php
Surface cardStatus badgeData table

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Cards

Pricing card

Reference recipe

A sample plan with price, billing period, limits and a clear selection action.

Studio

Sample plan

For a growing team, with room to create.

₹999/ month

Illustrative pricing · INR · taxes extra

  • Shared project space
  • Team collaboration
  • Client handoff

Select a plan to inspect its state.

Permalink
Usage & code

When to use

  • 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.

Variants

monthlyannualselected plan

Required states

defaultselectedbilling switchedprocessingfailed

Source & contracts

cora-frontend/components/pricing/PricingSection.tsx
Surface cardPricing / checkoutButtonCheckbox / radio / switch

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Cards

Blog and article card

Reference recipe

An editorial cover, topic, title, excerpt and reading metadata for a discoverable article.

Cora landscape artwork with layered hills and a clear sky
Studio journal

Make room for your best work.

A calmer way to organise projects, people, and everything in between.

Sample article5 min read
Explore the journal
Permalink
Usage & code

When to use

  • 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.

Variants

article cardfeatured articlerelated guide

Required states

defaultimage loadingimage unavailablelink focus

Source & contracts

cora-frontend/components/blog/BlogArticleCard.tsx
Surface cardDocs / articles / guidesIconography

Structural example

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.

primary
secondary
ghost
danger

Choose any enabled action.

Permalink
Usage & code

When to use

  • 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.

Variants

primarysecondaryghostdangericon with label

Required states

defaulthoverfocus-visibledisabledloading

Source & contracts

cora-frontend/components/design-system/primitives.tsx
ButtonIconography

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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></>
Controls

Form fields and validation

Shared primitive

Visible labels, supporting hints, required inputs, disabled controls and actionable field errors.

Use a name your team can recognise.

Example input; no message is sent.

Your current workspace.

No information leaves this preview.

Permalink
Usage & code

When to use

  • 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.

Variants

textemailhintrequirederrordisabled

Required states

emptyenteredfocus-visibleinvaliddisabled

Source & contracts

cora-frontend/components/design-system/primitives.tsx
Text fieldSelect / comboboxButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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 /></>
Controls

Checkboxes, radios and switches

Reference recipe

Native labelled selection for independent choices, exclusive options and a binary preference.

Default project view

Board view selected. Updates enabled.

Permalink
Usage & code

When to use

  • 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.

Variants

checkboxradio groupswitchnative select

Required states

uncheckedcheckedfocus-visibledisabled

Source & contracts

cora-frontend/components/design-system/CatalogPreviews.tsx
Checkbox / radio / switchSelect / combobox

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Controls

Tabs and segmented navigation

Reference recipe

Same-page panels with selected state, matching panel relationships and keyboard navigation.

Overview

A focused summary of your project, people, and next steps.

Use Left/Right arrows, Home, and End to navigate tabs.

Permalink
Usage & code

When to use

  • 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.

Variants

panel tabssegmented options

Required states

selectedunselectedkeyboard focuspanel visible

Source & contracts

cora-frontend/components/design-system/CatalogPreviews.tsx
Tabs / segmented controlNavigation shell

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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></>
Controls

Search and filters

Reference recipe

A labelled query with clear action, result count and an explicit no-results response.

3 projects found.

  • Studio launchSample
  • Brand refreshSample
  • Editorial sessionSample
Permalink
Usage & code

When to use

  • 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.

Variants

search inputcategory filterclear query

Required states

idleresultsno resultscleared

Source & contracts

cora-frontend/components/blog/BlogSearch.tsx
Search / filtersText fieldSelect / comboboxButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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></>
Overlays

Modal dialog

Shared primitive

A focused task with a labelled title, contained keyboard focus and explicit completion or cancellation.

A clear, focused decision.

A labelled modal keeps one task in focus, with an explicit close action.

Open the example to try keyboard focus and Escape.

Create a sample project

Demo data · You can close this panel without saving.

Permalink
Usage & code

When to use

  • 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.

Variants

centred modalnarrow-screen modal

Required states

closedopensubmittingvalidation errordismissed

Source & contracts

cora-frontend/components/design-system/primitives.tsx
Sheet / dialogText fieldButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Overlays

Drawer and mobile bottom sheet

Shared primitive

A contextual inspector positioned at the desktop edge and at the bottom of a narrow screen.

Details, without losing context.

A side panel on desktop becomes a reachable bottom sheet on a phone.

Open the example to try keyboard focus and Escape.

Project details

Demo data · You can close this panel without saving.

Project team

Alex · Morgan · Casey

In progress
Permalink
Usage & code

When to use

  • 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.

Variants

desktop side inspectormobile bottom sheet

Required states

closedopendetail selectedunsaveddismissed

Source & contracts

cora-frontend/components/design-system/primitives.tsx
Sheet / dialogSurface cardButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.tsx.

<Sheet open={isOpen} onClose={() => setIsOpen(false)} placement="drawer" title="Project details"><p>Selected sample project</p></Sheet>
Overlays

Destructive confirmation

Reference recipe

A custom confirmation that identifies the affected sample record and the consequence of proceeding.

Confirm with confidence.

Name the affected record and explain what changes before the user confirms.

Open the example to try keyboard focus and Escape.

Archive this sample project?

“Studio launch” will leave the active project list. Its files and activity remain available in the archive.

This demonstration only changes local preview feedback.

Permalink
Usage & code

When to use

  • 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.

Variants

remove recorddiscard changes

Required states

closedopencancelledconfirmingfailed

Source & contracts

cora-frontend/components/design-system/CatalogPreviews.tsx
Sheet / dialogButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Overlays

Toast and inline feedback

Reference recipe

Status messages that announce a local outcome and offer an explicit dismissal or recovery action.

Changes saved

Your sample project is up to date.

This is an in-flow specimen. Product features reuse their host notification system.

Permalink
Usage & code

When to use

  • 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.

Variants

informationalsuccesserrordismissible

Required states

idlevisibledismissedretry available

Source & contracts

cora-frontend/components/design-system/CatalogPreviews.tsx
Toast notificationStatus badgeButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.tsx.

<div role="status"><p>Sample changes saved.</p><Button variant="ghost" onClick={dismissMessage} aria-label="Dismiss saved message">Dismiss</Button></div>
Content

Accordion and disclosure

Reference recipe

Optional supporting information revealed through a named disclosure control.

What belongs in a project?

Tasks, people, files, and the context your team needs to move forward.

Can I use this on mobile?

Yes. Content stacks, touch targets remain reachable, and drawers become bottom sheets.

How do I keep the design consistent?

Reuse the documented components and semantic tokens. Extend the shared contract when a new pattern is needed.

Permalink
Usage & code

When to use

  • 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.

Variants

single disclosureFAQ group

Required states

collapsedexpandedkeyboard focus

Source & contracts

cora-frontend/components/blog/BlogFAQAccordion.tsx
Docs / articles / guidesButton

Structural example

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.
  • One primary action per decision.
  • Readable text in both themes.
  • Reachable controls on every screen.
Read the documentation
Permalink
Usage & code

When to use

  • 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.

Variants

article prosedocumentationinline codequote

Required states

readinglink focuscode overflow contained

Source & contracts

cora-frontend/components/blog/BlogBlockRenderer.tsx
Docs / articles / guidesMarketing hero

Structural example

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.

Permalink
Usage & code

When to use

  • 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.

Variants

first usefiltered emptyloading skeletonrecoverable error

Required states

loadingemptyerrorretrypopulated

Source & contracts

cora-frontend/components/design-system/CatalogPreviews.tsx
Empty / error / skeletonButtonSurface card

Structural example

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.

Sample projects · 3 records
SelectStatusBudget (INR)
Studio launchIn progress₹24,000
Brand refreshPlanned₹18,500
Editorial sessionPlanned₹12,000

0 projects selected.

Permalink
Usage & code

When to use

  • 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.

Variants

records tablefiltered tablemobile contained scroll

Required states

populatedloadingemptyfiltered emptyerrorrow action focus

Source & contracts

app/public/wp-content/plugins/cora-workspace/views/view-leads.php
Data tableStatus badgeButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Data & workflows

Kanban board

Reference recipe

A stage-based sample board with counts and a non-drag way to move records.

Planned

1
Studio launch

Brand direction · Sample task

In progress

0

No projects in this stage.

Complete

0

No projects in this stage.

Studio launch is in planned.

Permalink
Usage & code

When to use

  • 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.

Variants

stage columnsempty stagekeyboard move

Required states

populatedempty stagemovingmovedsave failure

Source & contracts

app/public/wp-content/plugins/cora-workspace/views/view-leads.php
Kanban boardSurface cardSelect / combobox

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Data & workflows

Workflow stepper

Reference recipe

A guided workflow showing completed, current and upcoming steps with reachable next/back actions.

  1. 1Details
  2. 2Terms
  3. 3GST Math
  4. 4E-Sign
  5. 5Complete
Step 1 of 5

Details

Add the project and client details.

Navigation demonstration; no signature or document is created.

Permalink
Usage & code

When to use

  • 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.

Variants

full sequencemobile current stepblocked progression

Required states

currentcompletedupcomingblocked

Source & contracts

app/public/wp-content/plugins/cora-workspace/views/view-vault.php
Guided workflowButtonText field

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>
Images & icons

Images and avatars

Reference recipe

Editorial 16:9, gallery 4:3 and square/avatar image frames with captions and fallback treatment.

Cora landscape illustration showing layered hills beneath a bright sky
Established Cora artwork · Cropped to fill a 16:9 frame.
AL

Avatar fallback · initials or an informative icon

Permalink
Usage & code

When to use

  • 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

Required states

loadedloadingunavailableselected

Source & contracts

app/public/wp-content/plugins/cora-workspace/views/view-media.php
Marketing heroSurface cardIconography

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.tsx.

<figure><img src={sampleCoverSrc} alt="Illustrated sample project workspace" width={640} height={360} /><figcaption>Sample editorial cover · 16:9</figcaption></figure>
Images & icons

File upload

Reference recipe

A labelled real file control with limits, local validation and explicit file-selection feedback.

No file selected. Nothing will be uploaded.

Permalink
Usage & code

When to use

  • 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.

Variants

file pickerdropzonefile summaryrejected file

Required states

idleselecteddrag-overuploadingcompleterejected

Source & contracts

cora-frontend/components/design-system/CatalogPreviews.tsx
File uploadText fieldButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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></>
Images & icons

Icons and meaningful labels

Reference recipe

Consistent SVG glyphs for navigation, actions, files, media and status, paired with accessible names.

Selected icon: Folder. Use a visible label or an accessible action name.

Lucide · consistent outline strokes · icons inherit the current text color.

Permalink
Usage & code

When to use

  • 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.

Variants

16px inline20px control24px tileicon with labelicon-only action

Required states

decorativelabelledfocus-visibledisabled

Source & contracts

cora-frontend/components/features/FeatureIcon.tsx
IconographyButton

Structural example

Implement the caller state and handlers. Preview compositions live in cora-frontend/components/design-system/CatalogPreviews.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>

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.

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.

Stack
Next.js App Router / React / Tailwind
Font
--cora-font-marketing
Canvas
--cora-bg

Reuse first

  • components/layout/Navbar.tsx
  • components/layout/Footer.tsx
  • components/tools/ToolPageShell.tsx
  • components/tools/framework/ToolContainer.tsx
Source referencescora-frontend/styles/globals.csscora-frontend/tailwind.config.tscora-frontend/app/layout.tsx
existing-baselineworkspace

Product workspace

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 first

  • window.coraShowToast
  • includes/workspace-header.php
  • Existing feature-local sheet and table markup
Source referencesapp/public/wp-content/plugins/cora-workspace/assets/css/admin-style.cssapp/public/wp-content/plugins/cora-workspace/admin-dashboard.php.agents/AGENTS.md
04 / REFERENCE

Design tokens

Exact values with explicit purpose. Use semantic names in components; raw palette values are reference material.

--cora-zinc-50

Neutral reference 50; prefer semantic tokens in components.

#fafafapalette
--cora-zinc-100

Neutral reference 100; prefer semantic tokens in components.

#f4f4f5palette
--cora-zinc-200

Neutral reference 200; prefer semantic tokens in components.

#e4e4e7palette
--cora-zinc-300

Neutral reference 300; prefer semantic tokens in components.

#d4d4d8palette
--cora-zinc-400

Neutral reference 400; prefer semantic tokens in components.

#a1a1aapalette
--cora-zinc-500

Neutral reference 500; prefer semantic tokens in components.

#71717apalette
--cora-zinc-600

Neutral reference 600; prefer semantic tokens in components.

#52525bpalette
--cora-zinc-700

Neutral reference 700; prefer semantic tokens in components.

#3f3f46palette
--cora-zinc-800

Neutral reference 800; prefer semantic tokens in components.

#27272apalette
--cora-zinc-900

Neutral reference 900; prefer semantic tokens in components.

#18181bpalette
--cora-zinc-950

Neutral reference 950; prefer semantic tokens in components.

#09090bpalette
--cora-white

Pure light surface / inverse text.

#ffffffpalette
--cora-cream

Existing workspace canvas and editorial backdrop; never a colored action.

#FBFAF7palette
--cora-workspace-dark

Current dark workspace canvas; cards remain neutral raised surfaces.

#0c0c0epalette
--cora-canvas

Surface-profile page canvas; workspace overrides this to cream or its dark canvas.

#ffffffsemantic
--cora-bg

Page and control surface.

#ffffffsemantic
--cora-surface

Secondary surface.

#fafafasemantic
--cora-selected

Tonal hover and selection.

#f4f4f5semantic
--cora-border

One-pixel structural borders.

#e4e4e7semantic
--cora-border-strong

Accessible input boundary; never heavy card selection. Recommended for new controls.

#71717asemantic
--cora-text

Primary text.

#09090bsemantic
--cora-muted

Supporting text on light surfaces.

#52525bsemantic
--cora-subtle

Metadata; do not reduce opacity on small text.

#71717asemantic
--cora-action

Primary action / dark icon tile.

#09090bsemantic
--cora-on-action

Text on primary action.

#ffffffsemantic
--cora-action-hover

Primary action hover.

#27272asemantic
--cora-focus

Visible keyboard focus; accessibility exception to decorative outline prohibition.

#52525bsemantic
--cora-success

Legible success text; always include label or icon.

#166534semantic
--cora-success-bg

Success surface only.

#f0fdf4semantic
--cora-warning

Legible warning text; never the primary CTA.

#854d0esemantic
--cora-warning-bg

Warning surface only.

#fefce8semantic
--cora-danger

Error / destructive text.

#b91c1csemantic
--cora-danger-bg

Error surface only.

#fef2f2semantic
--cora-font-marketing

Marketing body and headings; retain current runtime font.

'General Sans', var(--font-sans, Inter), -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-seriftypography
--cora-font-workspace

Operational workspace text.

var(--font-sans, Inter), -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-seriftypography
--cora-font-ui

Active surface font. Override through data-cora-profile.

var(--cora-font-marketing)typography
--cora-font-code

Code, identifiers, token values; use tabular figures for numeric data.

var(--font-mono, 'JetBrains Mono'), Menlo, Consolas, monospacetypography
--cora-text-caption

Role: caption. Base rem assumes 16px; respect browser zoom.

0.75remtype scale
--cora-text-code

Role: code. Base rem assumes 16px; respect browser zoom.

0.8125remtype scale
--cora-text-small

Role: small. Base rem assumes 16px; respect browser zoom.

0.875remtype scale
--cora-text-body

Role: body. Base rem assumes 16px; respect browser zoom.

1remtype scale
--cora-text-h3

Role: h3. Base rem assumes 16px; respect browser zoom.

1.125remtype scale
--cora-text-h2

Role: h2. Base rem assumes 16px; respect browser zoom.

1.5remtype scale
--cora-text-h1

Role: h1. Base rem assumes 16px; respect browser zoom.

2remtype scale
--cora-text-display

Role: display. Base rem assumes 16px; respect browser zoom.

3remtype scale
--cora-space-0

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

0pxspacing
--cora-space-1

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

4pxspacing
--cora-space-2

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

8pxspacing
--cora-space-3

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

12pxspacing
--cora-space-4

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

16pxspacing
--cora-space-5

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

20pxspacing
--cora-space-6

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

24pxspacing
--cora-space-8

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

32pxspacing
--cora-space-10

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

40pxspacing
--cora-space-12

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

48pxspacing
--cora-space-16

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

64pxspacing
--cora-space-20

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

80pxspacing
--cora-space-24

Four-pixel rhythm; choose by relationship, not arbitrary decoration.

96pxspacing
--cora-radius-sm

Controls: md/lg; cards: xl; sheets: 2xl; status: pill.

6pxradius
--cora-radius-md

Controls: md/lg; cards: xl; sheets: 2xl; status: pill.

8pxradius
--cora-radius-lg

Controls: md/lg; cards: xl; sheets: 2xl; status: pill.

12pxradius
--cora-radius-xl

Controls: md/lg; cards: xl; sheets: 2xl; status: pill.

16pxradius
--cora-radius-2xl

Controls: md/lg; cards: xl; sheets: 2xl; status: pill.

24pxradius
--cora-radius-pill

Controls: md/lg; cards: xl; sheets: 2xl; status: pill.

9999pxradius
--cora-shadow-sm

Subtle surface lift.

0 1px 2px rgba(0,0,0,0.05)elevation
--cora-shadow-sheet

Overlay elevation; do not apply to every card.

0 20px 50px rgba(0,0,0,0.12)elevation
--cora-backdrop

Recommended modal backdrop, verify module behavior before replacing legacy overrides.

rgba(9,9,11,0.45)elevation
--cora-duration-fast

Hover and focus feedback.

150msmotion
--cora-duration-normal

Small transitions; no artificial wait.

200msmotion
--cora-duration-sheet

Sheet movement; disable for reduced motion.

250msmotion
--cora-ease

Calm deceleration.

cubic-bezier(0.2, 0, 0, 1)motion
--cora-content-marketing

Current main marketing container, observed across shipped components.

1240pxlayout
--cora-content-editorial

Current editorial and business-tool shell width.

1100pxlayout
--cora-content-docs

Current documentation shell width.

1440pxlayout
--cora-content-workspace

Operational content maximum from legacy token specification.

1280pxlayout
--cora-content-reading

Recommended long-form prose width.

720pxlayout
--cora-control-height

Recommended minimum interactive target.

44pxlayout
--cora-drawer-width

Desktop panels only; mobile uses bottom sheet.

448pxlayout
--cora-z-menu

Local menus within the feature stacking context.

40layer
--cora-z-backdrop

Local overlay backdrop.

50layer
--cora-z-sheet

Local sheet/dialog.

60layer
--cora-z-toast

Local feedback above sheets; bridge existing global z-index carefully.

70layer
05 / REFERENCE

Typography

Roles create hierarchy. Marketing uses General Sans; operational UI uses Inter; code uses JetBrains Mono.

Display

Clarity in every detail.

--cora-text-display

600–700 weight · 1.1 line height

Marketing hero; clamp to 32px on mobile; existing campaigns may use larger type.

Page title

Clarity in every detail.

--cora-text-h1

600–700 weight · 1.2 line height

One h1 per page; operational headings may use 24px.

Section title

Clarity in every detail.

--cora-text-h2

600 weight · 1.3 line height

Sections / sheet headings, semantic h2.

Card title

Clarity in every detail.

--cora-text-h3

600 weight · 1.4 line height

Grouped content and card headings.

Body

Clarity in every detail.

--cora-text-body

400 weight · 1.6 line height

Reading, forms on mobile; product dense rows use small (14px).

Small

Clarity in every detail.

--cora-text-small

400–500 weight · 1.5 line height

Supporting copy and product rows.

Caption

Clarity in every detail.

--cora-text-caption

400–500 weight · 1.4 line height

Metadata; never essential input copy below 12px.

Code

Clarity in every detail.

--cora-text-code

400–500 weight · 1.6 line height

Copyable code; horizontal scrolling confined to its own block.

06 / REFERENCE

Live components

Real reusable primitives. Change the surface, theme and state to inspect the same contract in action.

marketing / light / INTERACTIVE EXAMPLE

Project details

A local preview. Changes here affect this example.

Visible to everyone in your team.

Use Tab to inspect visible keyboard focus.

Project summary

Active

Autumn campaign

DraftActivePendingOverdue
Client
Kavya Patel
Project status
Ready for review
Identifier
PRJ-024

Semantic status labels, tonal surfaces and subtle structural borders.

Project details

Responsive modal preview. On a phone, this becomes a bottom sheet. Escape or Close dismisses it and returns focus to the opener.

Demo input; no records are saved.

Sheet@/components/design-system/primitives

Props: open: boolean; onClose: () => void; title: string; placement?: sheet | modal | drawer (default: sheet); footer?: ReactNode; children: ReactNode

Token bindings: --cora-bg, --cora-border, --cora-backdrop, --cora-radius-2xl, --cora-drawer-width

<Sheet open={isOpen} onClose={() => setIsOpen(false)} title="Project details" placement="drawer">…</Sheet>
Button@/components/design-system/primitives

Props: variant?: primary | secondary | ghost | danger; loading?: boolean; all native button props

Token bindings: --cora-action, --cora-on-action, --cora-control-height, --cora-radius-lg

<Button variant="primary" loading={isSaving} onClick={save}>Save changes</Button>
TextField@/components/design-system/primitives

Props: label: string; hint?: string; error?: string; id?: string; all native input props

Token bindings: --cora-bg, --cora-border-strong, --cora-danger, --cora-text-body

<TextField label="Project name" hint="Visible to your team" required />
Badge@/components/design-system/primitives

Props: tone?: neutral | success | warning | danger; children: ReactNode

Token bindings: --cora-selected, --cora-success, --cora-warning, --cora-danger

<Badge tone="success">Active</Badge>
Card@/components/design-system/primitives

Props: all native div props; children: ReactNode

Token bindings: --cora-bg, --cora-border, --cora-radius-xl, --cora-space-6

<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.
  • 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.
Statesdefaulthoverfocus-visibledisabledloading
Atom

Text field

Shared primitive
components/design-system/primitives.tsx → TextField
  • 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.
Statesdefaultfocus-visibledisablederrorrequired
Atom

Status badge

Shared primitive
components/design-system/primitives.tsx → Badge
  • Neutral is the default. Success, warning and danger only communicate state.
  • Include human-readable status; never rely on a colored dot alone.
Statesneutralsuccesswarningdanger
Atom

Surface card

Shared primitive
components/design-system/primitives.tsx → Card
  • Subtle one-pixel border, 16px radius, 24px padding.
  • A card is not clickable by default; put an explicit link or action inside.
Statesdefaultselected (when selectable)empty
Foundation

Iconography

Existing pattern
lucide-react in marketing / existing SVG product icons
  • 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.
Statesdecorativelabelled
Atom

Checkbox / radio / switch

Existing pattern
Existing feature controls; prefer native inputs
  • Label the input; preserve checked, disabled and keyboard behavior.
  • Use tonal filled selection and a check indicator; no heavy dark card border.
Statesuncheckedcheckedfocusdisabled
Molecule

Tabs / segmented control

Existing pattern
Feature-local; no shared tab primitive yet
  • 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.
Statesselectedunselectedkeyboard focus
Atom

Select / combobox

Existing pattern
Native select preferred; feature-local custom menus
  • 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.
Statesclosedopenselectedemptydisabled
Molecule

Toast notification

Existing pattern
Marketing: components/ui/Toast.tsx; workspace: window.coraShowToast
  • 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.
Statesloadingpopulatedemptyfiltered emptyerrorselected
Organism

Kanban board

Existing pattern
Workspace CRM / lead views
  • 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.
Statesempty stagedraggingmovedsave failure
Molecule

Guided workflow

Existing pattern
Document creation and signature flows
  • 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.
Statescurrentcompletedupcomingblocked
Molecule

File upload

Existing pattern
Media / vault / tools views
  • 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.
Statesidledrag-overuploadingcompleterejected
Molecule

Date / schedule controls

Existing pattern
Crew scheduler and booking views
  • Display timezone and local format explicitly. Native controls are preferred where practical.
  • Calendar grids need keyboard navigation, selected date labels and unavailable state.
Statesavailableselectedunavailableinvalid
Molecule

Empty / error / skeleton

Existing pattern
Feature-local states
  • 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.
Statesloadingemptyerrorretry
Organism

Navigation shell

Existing pattern
Marketing Navbar/Footer; workspace header/sidebar
  • 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.
Statescurrentcollapsedexpandedmobile
Molecule

Search / filters

Existing pattern
Docs, tools and feature catalogs
  • Visible label, clear query, result count and useful no-results state.
  • Filters preserve query and communicate active state; URL state when sharable.
Statesidleresultsno resultscleared
Molecule

Tooltip / popover

Existing pattern
Feature-local contextual help
  • Help must be available on keyboard focus and touch, not hover alone.
  • Critical instructions belong in visible copy. Escape dismisses, focus remains stable.
Statesclosedopendismissed
Organism

Marketing hero

Existing pattern
components/hero/Hero.tsx and page-specific heroes
  • 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.
Statesdesktopmobilereduced motion
Organism

Feature / industry grid

Existing pattern
components/features and components/industry
  • Reuse domain data registry and existing card components.
  • One column on phone, two on tablet, three where readable; maintain heading order.
Statesallfilteredemptydetail
Organism

Pricing / checkout

Existing pattern
components/pricing/PricingSection.tsx and CheckoutSheet.tsx
  • 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.
Statesplan selectedbilling switchedprocessingfailedcomplete
Organism

Docs / articles / guides

Existing pattern
components/docs, components/blog, components/guides
  • Readable prose column, heading anchors, code overflow contained, mobile TOC.
  • Preserve current content schemas; provenance and updated dates remain visible.
StatesreadingTOC opensearching
Organism

Micro-tool shell

Existing pattern
components/tools/ToolPageShell.tsx; components/tools/framework/ToolContainer.tsx
  • 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.
Statesinitialvalid resultinvalid inputresetexport
Organism

AI input / execution feedback

Existing pattern
components/hero/HeroAIInput.tsx and feature-local agent panels
  • 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.
Statesidlecomposingprocessingresultfailure
08 / REFERENCE

Product & feature patterns

Design decisions across the product, beyond individual controls. Workspace source paths resolve under the cora-workspace plugin.

Shell, settings and permissions

Persistent navigation, profile popover, dynamic permissions, explicit unsaved-change save bar; no unscoped CSS.

Source referencesadmin-dashboard.phpviews/view-feature-hub.phpviews/view-cora-roles.phpviews/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.

Source referencesviews/view-leads.phpviews/view-clients.php

Tasks, projects and portfolio

Consistent detail panels, checklists and activity; preserve confidentiality and selected-record context.

Source referencesviews/view-client-task-manager.phpviews/view-projects.phpcora-frontend/app/portfolio/

Content, inbox and automation

Separate draft, processing, published and failed states. Preserve editor content; show recoverable service errors.

Source referencesviews/view-content-suite.phpviews/view-emails.phpviews/view-inbox.phpviews/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.

Source referencesviews/view-media.phpviews/view-media-editor.phppublic-gallery-view.php

Documents and signatures

Guided creation, labelled signature controls, audit state. Authored document fonts are content and remain outside interface typography restrictions.

Source referencesviews/view-vault.phppublic-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.

Source referencesviews/view-canvas.phpviews/view-visual-builder.php

Finance, inventory and scheduling

Tabular values, explicit currency/tax/timezone, empty states and permissions; equipment/listing terminology derives from industry.

Source referencesviews/view-financials.phpviews/view-equipment.phpviews/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.

Source referencesviews/view-forms.phpviews/view-review-acquisition.phppublic-form-view.phppublic-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.

Source referencescora-frontend/components/hero/cora-frontend/components/docs/cora-frontend/components/tools/framework/
09 / REFERENCE

Responsive layout

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.

  1. 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.
  2. Keyboard focus must remain clearly visible. A subtle focus outline is required even though heavy decorative outlines are forbidden.
  3. Use semantic landmarks, sequential headings, associated labels, native controls and an accessible name for every icon action.
  4. Announce asynchronous status without moving focus. Errors identify the field and explain how to recover.
  5. Modal focus is contained and restored; Escape and an explicit close work. Never place hidden panels in the tab order.
  6. Respect prefers-reduced-motion, browser zoom and touch input. No automatic marquee or smooth scrolling for reduced-motion users.
  7. 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.

  1. Use clear task language: Save changes, Create invoice, Move lead. Avoid technical infrastructure terms in customer workflows.
  2. Use fictional sample identities and no real owner or customer data in public UI or fixtures.
  3. Workspace labels resolve from active industry: equipment/property listings, shoots/showings, client/buyer leads. Do not hardcode industry names in shared views.
  4. Show currency, tax assumptions, dates and timezone explicitly. Keep identifiers and financial numbers tabular.
  5. 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.

Source referencescora-design-tokens.jscora-frontend/lib/cora-tokens.tscora-design-system.html
D02documented exception

Typography

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.

Source referencescora-frontend/styles/globals.csscora-frontend/components/brand/BrandTypographySection.tsx
D03migration required

Color

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.

Source referencesapp/public/wp-content/plugins/cora-workspace/tailwind.config.jscora-frontend/components/brand/BrandColorsSection.tsx
D04migration required

Mobile panels

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.

Source references.agents/AGENTS.mdapp/public/wp-content/plugins/cora-workspace/assets/css/admin-style.css
D05documented exception

Overlay backdrop

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.

Source referencesapp/public/wp-content/plugins/cora-workspace/assets/css/admin-style.css
D06documented exception

Feedback

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.

Source referencescora-frontend/components/ui/Toast.tsxapp/public/wp-content/plugins/cora-workspace/assets/js/admin-script.js
D07migration required

Accessibility

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.

Source references.agents/AGENTS.mdcora-frontend/components/providers/SmoothScrollProvider.tsx
13 / REFERENCE

The workflow for coding agents

Keep the implementation and its public contract in the same change.

  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.

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.

  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)

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.

Cora Design System / v1.1.0Back to start ↑