# Heartwood — the Cedros Design Standard

Version 2.18 · 2026-09-08 · Status: canonical

Heartwood is the durable source of truth for how Cedros looks, speaks, moves, and feels. The companion visual design system is `design-cedros.html`; update and review both together. Exact page compositions live separately in `design-cedros-examples.html`, which applies these rules to the homepage, assistant, and public pages. The board shows the approved campaign assets and product captures from `custom-pages/homepage/assets/` by relative path, so open it from the repository root.

This file contains enduring rules. Page-specific section order, asset lists, and choreography belong in implementation prompts, not here.

## Snapshot

| Attribute | Standard |
|---|---|
| Category | The operating system for AI built businesses |
| Promise | Websites that think, act, and work for you |
| Product model | A website and AI assistant in one package, sharing business context, tools, permissions, and workflows |
| Personality | Grounded · quietly capable · fast · warm precision · on your side |
| Public direction | Dark Pacific living infrastructure; obsidian, bone, stone, moss, oxidized teal, restrained bronze; documentary people and real product proof |
| Signature | Chat as an entrance, cedar-ring apertures, architectural flow, visible permission, recorded outcomes |
| Avoid | Generic AI SaaS, knowledge spheres, orbiting nodes, glass-card sprawl, resort imagery, neon, fake product UI, empty spectacle |

## Scope and precedence

- **Cedros brand register:** parent marketing, onboarding, campaign art, public assistant, and product storytelling follow this document.
- **Public theme kernel:** shared customer-site primitives inherit accessibility, state, interaction, and structural contracts, not the Cedros campaign aesthetic.
- **Customer themes:** customer identity remains configurable through semantic tokens and theme contracts.
- **Workspace:** `design-admin.md` wins inside `/admin`.
- **Extensions:** inherit host tokens and behavior; no unrelated chrome, palette, or terminology.
- **Implementation prompts:** may be more specific but may not contradict this standard.

Keep the public `--cedros-*` and `--cds-*` token layers separate. Their meanings are load-bearing.

## Register

| Register | Ground | Type | Density | Motion |
|---|---|---|---|---|
| Workspace | Neutral white / near-black | Compact sans | Dense, calm, tool-like | Fast state explanation |
| Cedros brand | Obsidian, bone, stone, environmental media | Editorial display + product sans | Composed, spatial, evidence-rich | Narrative and environmental |
| Customer theme | Theme-defined | Theme-defined roles | Appropriate to purpose | Theme-specific within shared limits |

Moving from marketing to admin should feel like moving from landscape and showroom to workshop: the same structure and precision at a different intensity.

## Use

- Public design: §§1–5, 7, 9; deeper product, pricing, and contact pages: §§5.9–5.11.
- Copy: §6.
- Motion: §7.
- Public assistant and homepage: §8.
- Workspace: shared principles here, then `design-admin.md`.
- PR review: §9.

## 1. Brand positioning

### 1.1 What Cedros is

AI is moving to both sides of the market. It is making new businesses easier to create, while agents are beginning to act on behalf of customers. Between them sits a web built for people to read and click. An agent can scrape a page, but it cannot reliably know what the business authorizes, invoke its capabilities, settle a transaction, or verify that its state changed.

Every business therefore needs one authoritative operating surface, and the domain is the natural place for it: it is already the business's public, persistent address. Cedros turns the website into that surface. People continue to use a normal website. Owners use the workspace or a conversation. Agents use machine-readable context and approved capabilities. All of them operate the same business state, under the owner's permissions. Records and undo are specific to the action and the product.

Agentic commerce is the first consequential proof to establish; do not imply a live agent checkout without verified product evidence. The larger product is the operating system connecting AI-built businesses with agent-mediated demand: as AI creates more businesses and represents more customers, Cedros becomes the layer between them.

Cedros is, concretely, a website platform with an agent runtime built in: content, commerce, customer communication, business context, tools, permissions, workflows, and history in one state.

### 1.2 Locked message hierarchy

| Role | Language |
|---|---|
| Category | The operating system for AI built businesses. |
| Primary promise | Websites that think, act, and work for you. |
| Supporting promise | Turn your website into a working part of your business. |
| Platform proof | AI builds better on Cedros. |
| Conversational entry | What are you building? |
| Composer placeholder | Describe your business, ask about Cedros, or tell us what you want the website to handle. |

Use these as a hierarchy, not interchangeable slogans. New headlines should prove or clarify them.

### 1.3 Story order

1. **The shift:** AI helps businesses build faster, build better, and keep improving. Customers are beginning to use agents to find, compare, and act. The website must connect these two changes, beyond pages built for reading and clicking.
2. **Built together:** the website is where customers meet the business. Keep its knowledge and working tools in the same system, designed for the assistant to use under the owner’s permissions. Explain this benefit before the domain architecture.
3. **Three ways in, one state:** people through a normal website, owners through the workspace or a conversation, agents through machine-readable context and approved capabilities.
4. **Authorization and record:** permissions decide what each may do; show the record supported by the action.
5. **Proof:** distinguish website quality from platform breadth, then establish the foundations an owner can reuse. Offer useful starting points and supported recommendations; explain assistant mechanics only where they help the decision.

Make the consequence explicit for the founder: build with AI and be ready for customers who use it, too. Connect that need to the website’s shared context and authorized tools; do not leave the two trends as unrelated observations.

Describe the system before the features. Do not lead with trivial examples (business hours, order packing); choose requests that cross several parts of the state and would matter to a founder.

### 1.4 Audience and benefit

Speak first to capable non-specialists: owners, operators, creators, founders, consultants, and small teams. The parent brand must also make sense for ecommerce, SaaS, agencies, developers, extension authors, and AI builders.

Prefer: helps people do more; handles repetitive work; helps customers while the owner is occupied; keeps work moving; makes knowledge reusable; gives owners visibility and control.

Avoid: "without a bigger team," replace staff, eliminate headcount, do more with fewer people, autonomous business, or runs itself.

### 1.5 AI and trust

AI is a useful mechanism, not the visual theme or a promise of unbounded autonomy.

Show it as grounded in business context, using approved tools, constrained by permissions, asking for clarification, requesting review, completing allowed actions, and leaving a record.

Cedros holds storefronts, customer information, credentials, content, and revenue. State, risk, uncertainty, permission, provenance, and history must be visible. Demonstrations are labeled. Generated campaign art is never product evidence.

### 1.6 Personality

Cedros is a calm operator inside durable infrastructure:

- Grounded, material, and built to last
- Quietly capable rather than performative
- Fast and respectful of attention
- Precise without becoming cold
- Clearly on the user's side
- Coherent across brand, product, chat, and system explanation

It must not feel like a toy builder, generic AI SaaS, enterprise sprawl, luxury resort, architecture studio, cyberpunk product, local-business-only tool, or opaque automation system.

### 1.7 Clarity test

Within 5 seconds, a visitor should know Cedros is about websites. Within 10 seconds, they should understand that the website can help the business do useful work.

## 2. Design principles

| Principle | Rule | Test |
|---|---|---|
| Quiet surface, loud state | Restrain decoration; make real state explicit. | Squint: state should out-rank ornament. |
| Speed is the aesthetic | Useful controls work immediately; motion never delays action. | Did theater make the user wait? |
| One emphasis per view | One dominant action or idea in each view or scene. | Can a newcomer name it in 3 seconds? |
| Plain words, real outcomes | Explain what happens in the user's world. | Would an owner ask "meaning what?" |
| Earn density and space | Dense tools need hierarchy; spacious scenes need composition. | Could half the space disappear without loss? |
| Familiar surface, deeper system | Keep the website recognizable while revealing depth progressively. | Is the action clear before the architecture? |
| Product proof over abstraction | Prefer real interface states and outcomes. | Could product evidence replace this diagram? |
| Human control is visible | Show context, proposal, permission, decision, and result. | Can the permission boundary be identified? |
| Durable over trendy | Choose materials and behavior that age well. | Would it work in 2020 and 2030? |
| Everyone, every input | Keyboard, touch, reduced motion, localization, and both modes are required. | Enlarge text 35%, unplug the mouse, and complete the task. |

## 3. Theme architecture

### 3.1 Neutral public kernel

The kernel supplies semantic color and type roles, layout, responsive containers, buttons, forms, navigation behavior, state patterns, accessibility, media handling, motion contracts, and optional chat primitives.

It must not hardcode Cedros marketing imagery, typography, or coastal palette into customer sites.

### 3.2 Cedros marketing preset

The parent-brand preset (`custom-pages/theme/cedros-heartwood.theme.json`) maps the kernel to:

- Obsidian, bone, stone, moss, oxidized teal, cedar, and bronze
- Editorial display type and neutral product sans
- Living-infrastructure media and documentary business scenes
- Cedar-ring apertures and architectural flow
- Chat-first entry through the `canvas` home surface and `overlay` nav
- Real product proof and operational annotations
- Both color modes, authored: environmental and product sections stay dark in either mode, editorial sections follow the visitor's mode, and the nav over media is always bone (§4.9)

### 3.3 Customer themes

Customer themes may change palette, type, imagery, spacing, and composition while preserving semantic contracts, accessibility, state clarity, and interaction behavior. Never solve a Cedros marketing problem by globally restyling customer sites.

### 3.4 Workspace

Inside `/admin`, follow `design-admin.md`. Heartwood contributes voice, trust, status meanings, and high-level personality; Workbench controls workspace layout, components, density, and motion.

### 3.5 Shell rule

No shared wrapper may force every public page into one rounded, pale, bordered sheet. Public architecture must support full-bleed media, dark and light sections, product theatres, conventional reading and commerce pages, sticky narratives, and customer-configurable themes.

The homepage owns its edge-to-edge contract twice: the theme's `canvas` surface removes the frame, and the page's own stylesheet neutralizes the frame so a host bundle that predates `canvas` still renders it edge to edge. The public render namespaces every kernel class per build (`<hash>-site__main`, not `cedros-site__main`), so those rules match by class suffix (`main[class*="-site__main"]:has(.hw)`, `[class*="-runtime__block"]:has(.hw)`), never by prefix. A staging or production host running an older bundle is not a reason to accept the frame.

Section height is content-led by default. Use viewport height only when composition or interaction earns it.

## 4. Visual identity

### 4.1 Color

| Role | Token | Value | Use |
|---|---|---|---|
| Obsidian | `--cd-brand-obsidian` | `#0D0D0E` | Full-bleed dark ground |
| Ink | `--cd-brand-ink` | `#07111F` | Dark type and product framing |
| Bone | `--cd-brand-bone` | `#F6F5F2` | Light ground and inverse text |
| Paper | `--cd-brand-paper` | `#FFFDF7` | Editorial and document surfaces |
| Cream | `--cd-brand-cream` | `#FAF6EA` | Warm alternate surface, never the universal shell |
| Stone | `--cd-brand-stone` | `#D9D7D2` | Structural neutral and borders |
| Slate | `--cd-brand-slate` | `#6E6E72` | Quiet metadata |
| Moss | `--cd-brand-moss` | `#3F5A4A` | Organic support |
| Oxidized teal | `--cd-brand-oxidized` | `#315B59` | Deep coastal accent |
| Cedar | `--cd-brand` | `#2F6C7D` light / `#7FB0BD` dark | Links, selected state, location, Cedra presence |
| Bronze | `--cd-brand-bronze` | `#B48755` | Sparse routes and operational focus |
| Rust | `--cd-brand-rust` | `#9B5B3F` | Rare material contrast |
| Gold | `--cd-gold` | `#E8BE75` | Approval and true milestones only |

Rules:

- Cedar marks brand presence, links, selection, and active location.
- Bronze marks sparse environmental flow or operational focus.
- Gold marks approval or a true milestone, not ordinary CTAs.
- Green = success, amber = warning, red = error, blue = information.
- Dark Pacific color comes mainly from imagery and materials, not bright interface washes.
- Customer themes map their own palette through semantic tokens.
- Components consume tokens; no scattered hardcoded color.
- Verify contrast in every mode and over media.

### 4.2 Typography and identity

**Brand mark.** Use the supplied Cedros identity without redrawing, tracing, patterning, or continuously animating it. The official cedar-ring C is now available in the repository’s brand assets; asset presence and installation into the site header are separate. Configure site identity through Settings › Site › Brand (`brand.logoUrl` / `brand.logoAssetId`, referenced by the theme’s `brandKit.assets`). Where a wordmark asset is unavailable, set the name in the display face beside the official mark. The kernel’s square-and-dot remains an installation placeholder, not the Cedros identity.

**Fonts.** The brand ships Newsreader for display, IBM Plex Sans for interface and body, and IBM Plex Mono for annotations. The marketing publish installs them as site media (`scripts/marketing-site/publish.mjs`); the theme kernel exposes them as `--cedros-font-heading`, `--cedros-font-body`, and `--cedros-font-mono`. Do not add arbitrary remote fonts to imitate a reference.

```css
--cd-font-sans: "IBM Plex Sans", "Avenir Next", "Segoe UI", sans-serif;
--cd-font-serif: "Newsreader", "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
--cd-font-mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
```

| Role | Guidance |
|---|---|
| Hero display | Editorial serif, `clamp(2.6rem, 5.4vw, 5.6rem)`, line-height 0.92–1.02; the whole H1 and conversation entry fit above the fold at 1280×800 and 1440×900 |
| Section display | Serif or selected sans, `clamp(2rem, 4vw, 3.75rem)` |
| Product heading | Sans, 500–600, compact |
| Lead | `clamp(1.05rem, 1.5vw, 1.35rem)`, line-height 1.45–1.6 |
| Body | 15–18px public; workspace follows `design-admin.md` |
| Metadata | 11–13px, muted, tabular where relevant |

Do not make the whole page serif, center every headline, or use tiny tracked uppercase on every object. Keep prose near 60–72 characters per line.

**Label budget.** Tracked uppercase is reserved for one kicker per section (the line above the heading). Every other label inside panels, frames, captions, chat messages, tags, and ledgers is sentence case at 12–13px in the sans or mono face. Mono is for provenance and state (`source: Rush orders · approved`), not for headings or decoration.

### 4.3 Layout and spacing

```css
--cd-gutter: clamp(1rem, 3vw, 3rem);
--cd-section-space: clamp(4.5rem, 10vw, 10rem);
--cd-section-space-compact: clamp(3rem, 6vw, 6rem);
--cd-reading: 68ch;
--cd-content: 76rem;
--cd-wide: 100rem;
```

Use a 4px base grid. Product proof must be large enough to inspect. Full-bleed media may exceed containers. Mobile spacing is authored rather than proportionally shrunk. Empty height is not composition.

### 4.4 Geometry and surfaces

Public preset radii: 6px compact, 8px ordinary, 12px feature/dialog, pill only for true chips and avatars. These are the shipped `tokens.radius.sm/md/lg/pill` values; concentric inner corners subtract the actual border and padding inset from the parent radius, floored at zero. Never use pills for state vocabularies, capability lists, step tabs, or any row of labels.

Use square or subtly rounded architectural planes. Depth comes from material, overlap, border, and tint before shadow. Avoid universal 24–32px rounding, colored glows, heavy backdrop blur, blue glass, and a border around every group. Prefer ledgers (ruled rows, a left accent for the active item) over stacks of bordered boxes; a section should normally carry one boxed object being examined (a document, a product frame, a result). A compatibility composition may show several recognizable app windows when their relationship is the subject (§4.7).

### 4.5 Brand imagery

The parent-brand world is living infrastructure embedded in a dark Pacific coast. Keep its cinematic depth, material texture, and restrained light. Imagery must help someone recognize the product or the business using it; atmosphere alone cannot explain Cedros.

Use rugged coastline, fog, cedar or cypress, stone, concrete, dark metal, glass, monolithic structures integrated into terrain, circular openings, retaining walls, passages, contours, and sparse warm operational light.

Avoid luxury housing, resorts, spas, surf lifestyle, data centers, military bunkers, science-fiction cities, cyberpunk, and crypto worlds. Polished terraces, path uplights, reflecting pools, and furnished rooms read as hospitality; reject them at candidate review.

Generated environments need deliberate desktop and mobile compositions, real text-safe areas, and physical plausibility.

Judge campaign images with all copy removed: the subject, action, and relationship to the product must still be clear. Represent internet-native businesses as well as physical ones. A living website may be personified to explain the website-and-assistant package; keep the metaphor legible, distinguish it from product evidence, and avoid implying an autonomous business.

### 4.6 Human imagery

Use candid documentary-style business scenes, including in the hero when they make the product story more concrete. People are occupied, competent, and connected to real work. Avoid posed laptop photos, staged smiles, boardrooms, high-fives, coworking stock, and luxury retail.

Generated people illustrate a business scenario; they are never customer evidence. Connect the activity to a meaningful business or product action that is understandable without the copy. A human scene may carry one compact Cedros outcome panel placed on the calm area the media manifest reserved for it, never over the person or the work. It may not be covered by dashboards.

### 4.7 Product evidence

Use actual supported Cedros interfaces at a readable scale, with believable seeded data and no private information. Do not generate fake UI, metrics, customers, routes, or capabilities.

Capture whole cards and whole rows at 2× device pixels, using a 1440px admin viewport for desktop and the actual narrow product layout for phone displays, so every label is legible and no sentence is cut at the frame edge. Give smaller screens a keyboard-accessible way to inspect the original at a readable scale; preserve focus when closing it. A frame may crop to a region but the region must be a complete object. Recapture whenever the admin UI materially changes (`scripts/homepage-media/capture.mjs`).

Recognizable interface illustrations may explain tool compatibility. Label them, preserve the familiar interface structure, and distinguish documented connections, custom setup, built-in workflows, and mobile surfaces. They are not product captures or evidence of a completed integration. Never invent live activity or copy private account data.

A labeled demonstration may use representative data, but must not present simulated activity as real. A generated photographic setting may hold an unaltered product capture as a separate HTML layer; never ask image generation to redraw the interface. Keep the original capture inspectable and distinguish real interface evidence from illustrative surroundings.

### 4.8 Operational annotation

Use fine rules, restrained markers, concise status language, and clear relation to the event. Suitable labels include "Question answered," "Follow-up prepared," "Review required," "Page updated," and "Completed and recorded."

Keep simultaneous annotations sparse. Avoid HUDs, telemetry clutter, cyan glow, coordinate theater, and decorative node networks. A connector line must end at something; a label that floats over a photograph with no anchor is decoration.

### 4.9 Icons, states, and modes

Use Lucide-compatible stroke geometry: a 24-unit grid, 2-unit stroke, round caps and joins, no fill, and `currentColor`. Public controls use 20px icons by default; 16px fits metadata and 24px fits standalone controls. Keep the surrounding target at least 44px. Decorative icons are hidden from assistive technology; icon-only actions have an accessible name, with optional explanatory help available by keyboard and touch. No emoji, duotone systems, AI stars, robots, or gradients inside icons.

Canonical states:

- **Empty:** what this is, what it enables, one action
- **Loading:** layout-matched skeleton; name work after 1 second
- **Error:** what happened, effect on the user's work, next step, reference ID when available
- **Success:** short outcome; milestone treatment only for meaningful achievements
- **Approval:** proposed action, scope, source, permission, and confirming verb

Light and dark are designed, not inverted. Adjacent sections must retain a visible change of surface or a deliberate divider in both modes. Distinguish dark environmental ground, editorial ground, and raised panels instead of flattening all three to near-black. Preserve the rhythm of background bands when reordering content; review the boundary with both neighboring sections in view. Set `color-scheme` before paint. The marketing preset keeps the visitor's mode choice (footer toggle): environmental and product-theatre sections are dark in both modes, editorial sections switch between bone and near-black surfaces, and the overlay nav over media reads bone until it scrolls onto a solid surface. Review the homepage in both modes; an inverted shell around a dark page is a defect, not a mode.

Meet WCAG 2.2 AA, visible focus, keyboard and touch parity, live-region support, 35% text growth, and RTL where supported. Important text remains live HTML.

### 4.10 Semantic roles and token ownership

The campaign palette in §4.1 describes materials. Interface text, controls, and focus use paired semantic roles from `custom-pages/theme/cedros-heartwood.theme.json`, compiled by `ui/src/site-templates/themeKernelTokenCompiler.ts`:

| Role | Public token | Light | Dark |
|---|---|---|---|
| Ground | `--cedros-background` | `#F6F5F2` | `#0D0D0E` |
| Text | `--cedros-foreground` | `#07111F` | `#F6F5F2` |
| Quiet surface | `--cedros-muted` | `#EDEBE6` | `#17181A` |
| Secondary text | `--cedros-muted-foreground` | `#5F6065` | `#A6A7A9` |
| Decorative divider | `--cedros-border` | `#D9D7D2` | `#2A2B2D` |
| Link | `--cedros-link` | `#2F6C7D` | `#7FB0BD` |
| Primary action fill | `--cedros-primary` | `#0D0D0E` | `#F6F5F2` |
| Primary action text | `--cedros-primary-foreground` | `#F6F5F2` | `#0D0D0E` |
| Selected surface | `--cedros-accent` | `#E7EEEF` | `#1D2A2C` |
| Focus / control boundary | `--cedros-ring` | `#2F6C7D` | `#7FB0BD` |
| Success text / icon | `--cedros-success` | `#166534` | `#4ADE80` |
| Error text / icon | `--cedros-error` | `#B91C1C` | `#F87171` |

- Pair foreground with background and primary text with primary fill. A material swatch is not automatically an accessible text color. Accent is a surface, never foreground text.
- A decorative divider may be quiet; an input boundary or state indicator that is necessary to identify a control must remain perceptible. Use the focus/link role for necessary boundaries when the decorative border is too faint.
- Success and error use their semantic role plus a word or icon. Warning and information retain normal readable foreground with an explicit label; this public manifest does not expose warning/info color fields. Never invent those manifest keys.
- `--cedros-*` values are the configurable public inputs. The kernel resolves its local `--cds-*` aliases. `--cd-*`/`--admin-*` belong to Workbench; the historical `--cd-brand-*` notation in this document is a design reference, not an additional public runtime API. Board-local CSS variables are specimens, not classes an extension may depend on.
- Theme tokens define the ordinary public shell. The authored campaign canvas has its own wider containers and section spacing (§4.3). A 46rem content / 75rem wide preset shell and a 76rem / 100rem campaign composition are deliberate different scopes.

### 4.11 Scales, elevation, and responsive composition

| Foundation | Public rule |
|---|---|
| Spacing steps | 4 / 8 / 12 / 16 / 24 / 32 / 48px; 8–12px within a control group, 24–32px between related groups |
| Control size | Minimum 44px height and icon target; 52px for a prominent acquisition action; height may grow when labels wrap |
| Control type | 16px body/input, 14px short button labels, 12–13px metadata; controls use sans, 500 for labels |
| Compact title | 20px / 1.25, sans 500–600; editorial display and body roles remain §4.2 |
| Internal padding | 12–16px horizontal for controls; 24px ordinary panel, 16px narrow; no fixed-height prose panels |
| Shape | 6 / 8 / 12px, then pill only for chips and avatars; subtract inset for nested corners |
| Elevation | Ground: none; contained object: border or `--cedros-shadow-sm`; anchored overlay: `--cedros-shadow-md`; modal: `--cedros-shadow-lg` plus backdrop |
| Layer order | Content → sticky navigation → anchored popover → modal/backdrop → modal-local feedback. Put a modal in the top layer; do not compete with arbitrary large z-index values. |

The preset's shadow recipes are `0 1px 2px rgb(13 13 14 / 6%)` (small), `0 4px 6px -1px rgb(13 13 14 / 10%), 0 2px 4px -2px rgb(13 13 14 / 8%)` (medium), and `0 10px 25px -4px rgb(13 13 14 / 12%), 0 4px 6px -1px rgb(13 13 14 / 10%)` (large). In dark mode, a visible edge and surface separation carry depth; shadow alone is insufficient. The public compiler has no z-layer manifest group. Reuse host layers and native top-layer primitives rather than adding one.

Use content-driven breakpoints. The board demonstrates split-to-stacked composition at 980px and compact groups at 680px; these are specimen breakpoints, not a required kernel API. At narrow widths: navigation becomes a disclosure, comparison columns become labeled rows or an explicitly scrollable table, actions wrap in reading order, and forms use one column. Keep the primary action reachable with the virtual keyboard open. Preserve DOM reading order; CSS must not move essential instructions after their controls.

Prose, errors, and control labels wrap. Identifiers wrap or scroll inside their frame and remain available in full. Use `min-width: 0` in flexible children. Truncate only a constrained navigation/list label whose full value is available through an accessible detail surface; a hover title alone is insufficient on touch. Never truncate a price or hide part of a required instruction.

### 4.12 Numbers, technical content, and charts

- Quantities, prices, percentages, and dates use sans with tabular numerals where values align. Use locale formatters, show currency and billing interval, and disclose the time zone when it changes the meaning. Abbreviations must have a reachable exact value.
- Identifiers, paths, and code use mono; human names and email addresses use sans. Preserve copyable values in full. A copy control reports success only after the clipboard write succeeds, reports failure with a manual selection path, and does not move focus. Secrets use the existing protected credential flow, never a public specimen containing real credentials.
- Code blocks have a language/filename label when useful, a readable mono body, contained horizontal scrolling, and one copy action. Inline code wraps. Prose uses headings, lists, quotes, and links with visible hierarchy; links remain distinguishable in running text.
- Metrics name the quantity, period, and comparison basis. Missing is not zero. Charts have a title, units, direct labels, and an accessible data table. Color is supported by labels or shape. Empty, loading, and unavailable charts are distinct.
- For categorical charts, use cedar first, then gold, sage, clay, indigo, and mist (§4.1 plus Workbench §4.9); verify contrast on the actual surface. Semantic success/error series retain their meaning. No gradients, 3D bars, unexplained dual axes, invented precision, or fabricated customer evidence. Bar charts start at zero; disclose any nonzero line-chart axis. Static specimen data is explicitly labeled illustrative.
- Public chart implementation reuses the owning renderer. Workbench's `--cd-chart-*` names are not public manifest fields. Data motion follows §7: one optional first reveal, stable geometry on refresh, final numbers exposed to assistive technology.

## 5. Composition and components

### 5.1 Navigation

Use the official identity, sparse real information architecture, a quiet Sign in action, and one current acquisition action.

- Transparent or minimal over dark hero media
- Solid or lightly blurred after meaningful scroll
- Correct contrast over light sections
- Thin architectural divider, not a large capsule
- Designed mobile menu and visible focus
- Text navigation sits directly on the header surface, without a differently colored inner bar
- Current location uses stronger text and a persistent underline plus `aria-current="page"`; hover and keyboard focus remain distinct
- No beige active-page pill or dead route

Share this navigation behavior across public routes. Fix the kernel’s text-navigation primitive and critical first-paint styles together; a page-local patch is not a sitewide fix. Overlay versus solid header is a surface choice, not a different active-page treatment.

Chat never replaces ordinary access to pricing, docs, support, sign in, or accessibility information.

### 5.2 Section modes

Prefer a small set of strong compositions:

- Full-bleed environmental media
- Dark product theatre
- Light editorial or document section
- Split human-outcome scene
- Conventional content section
- Compact conversion or pricing section

Each major viewport has one main idea. Do not repeat centered headline + card grid, and do not repeat "kicker, serif heading, lead, panel on the right" in every section either: alternate stacked heads with split heads (heading left, lead right), vary the anchor (media, document, ledger, product frame, conversation), and let at least one section in three run full width. The same photograph may anchor at most two sections of a page.

### 5.3 Actions and forms

Use one primary action per view, supported by secondary, ghost, and text-link levels. Buttons are sentence case, stable during loading, and use progressive verbs. Bronze and gold are not default fills.

Labels sit above fields. Helper and error text occupy one stable location. Validate on blur or submit. Public controls provide 44px touch targets, visible focus, clear completion, and accessible errors.

In-page links move to and focus their destination below the sticky header, including repeat activation. Preserve the route, query, browser modifier keys, and history state; a changed URL fragment without a visible destination is a broken action.

### 5.4 Chat

Chat is a first-class interface, not a corner widget.

The composer is immediately usable, labeled, mobile keyboard-safe, and supports focus, sending, loading, disabled, retry, offline, and preserved-input states. It must look like a conversation, not a form: a header naming the assistant and its verified state, the assistant's opening prompt as the first message, a visibly inset text field with a filled send control, and a few prompt buttons beneath it. The full placeholder is visible at rest; size the field for two lines rather than clipping the second.

The inset field carries one focus indicator while its textarea is active. Keep the outer conversation frame stable; send and suggestion controls retain their own keyboard focus indicators.

The thread distinguishes user, assistant, system state, source, approval, and action; uses real output and `aria-live="polite"`; and does not imitate a terminal or generic ChatGPT shell.

### 5.5 Product frame

A product frame shows one authentic state at a useful scale. It may crop or focus but may not distort, reskin, or obscure the product.

A product theatre may progress through multiple states while the outer frame remains stable. A control changes the relevant product view, caption, and inspection target together. Use a labeled icon grid for exploring many tools; organize by the work people do, rather than appending new features arbitrarily. Hover may preview, but click or tap holds the selected view until explicitly released or replaced. Keyboard users can select the same views. Moving toward Inspect must never change its target.

Match the device frame to the viewport: phone, laptop, then wide monitor. Capture the actual narrow interface for a phone. The framed preview shows the top of the page; Inspect reveals more of the same page in a readable, scrollable view, with a clear close action and restored focus. Preserve the previous image until the next is decoded, with a matching backing surface; no white flash between dark captures.

Accordion explanations, where appropriate, open beneath their own headings and can close again. Animate work inside the product; do not fly the whole dashboard through 3D space.

### 5.6 Human outcome panel

Use one compact panel with a few truthful outcomes, such as a question answered, booking confirmed, follow-up prepared, review required, or page updated. No fake counts, glowing cards, or multiple overlays.

### 5.7 Cedar-ring geometry

The ring may reveal a layer, express permission, connect environment to product, or close a sequence. It must not become a spinner, target, radar, ripple, or generic portal, and it is never a stand-in for the official mark.

### 5.8 Workspace components

Cards, tables, menus, dialogs, settings, dashboards, and command surfaces inside `/admin` follow `design-admin.md`. Across all surfaces, preserve one subject per panel, explicit state, exact destructive language, real loading/error states, undo for reversible actions, and no hidden risk.

### 5.9 Detailed product pages

About and product-overview pages serve visitors who want to understand the platform after the homepage. Explain what it is, how the website and workspace share records, what the tools do, and what setup or permissions they need. Use concrete customer-facing headlines; internal outline labels are not finished copy.

Use a readable article column, a compact chapter index, ruled capability groups, and optional disclosures for detail. Keep essential definitions visible. The index follows reading position, works with keyboard and touch, and becomes a compact in-flow list on smaller screens. Dense explanation is useful here; repeated campaign slogans are not.

Separate core tools, installable extensions, and connected services. Examples identify their source, requested work, and review boundary. Updating a source document does not automatically change checkout prices, publish content, or send a campaign. Explain supported build, code-conversion, and migration paths without promising unchanged transfer of an arbitrary site.

### 5.10 Pricing and programs

Pricing is a decision surface. Pair editorial headings with compact sans labels, a stable billing selector, aligned plan comparisons, grouped shared capabilities, and readable capacity guidance. Use surface contrast and fine rules before badges or decorative cards. Reflow comparison tables on mobile while preserving row and column meaning.

- Prices, currencies, billing intervals, annual totals, discounts, trials, and purchase actions come from the verified catalog. An annual monthly equivalent must identify the full annual charge.
- Distinguish included capabilities from quantities, collaboration limits, provider setup, paid extensions, and external charges. “Included” must not imply unlimited usage or every connected service being free.
- Give shared capabilities a complete, grouped inventory that can be scanned without opening every row. Keep plan-specific limits with the plan and avoid repeating the same feature list in both columns.
- Explain production-site capacity, managed AI usage, campaign email, and separately billed providers in plain language. Do not conflate campaign volume with transactional messages.
- Missing or failed catalog data gets an honest unavailable/contact state and retry where supported. Never infer a price or route checkout to a different plan. Loading and failure preserve the billing choice and comparison layout.

Program positioning must describe the reason to choose it:

| Path | Decision it supports |
|---|---|
| Individual | A primary operator running their own site |
| Business | Several people working within one organization, with shared context and team permissions |
| Developer | Building and hosting many sites, with more hosting and less Cedros-managed AI capacity; supported personal provider keys remain an option |

Developer is not the agency, reseller, or client-handoff path. Keep its summary, detail page, FAQs, and search metadata aligned. Exact prices and allowances belong in the catalog and product documentation, not this design standard.

### 5.11 Contact and service pages

Make the human contact route clear: a concise reason to write, one native form, and a few useful alternatives. On desktop, pair introduction and resource links with the form; on mobile, put the form before secondary resources. Keep the shared header and visitor’s color mode.

Reuse the platform’s form, validation, submission, privacy, and feedback behavior. Style the existing blocks rather than building a separate messaging path. Labels stay visible above fields; field errors, pending state, and retry remain accessible. Confirm receipt only after the server accepts the submission, preserve the message on failure, and never promise a response time without an actual service commitment.

### 5.12 Public component chooser and anatomy

These are public design contracts. Reuse the existing theme/form/navigation renderer; an HTML specimen does not establish a shipped component export (§9.8).

| Job | Anatomy and choice | Required behavior |
|---|---|---|
| Navigate | Text link; button-styled link only for a major destination | Real URL, current-page indication, browser history and modifier keys preserved |
| Act | Primary, secondary outline, ghost, or destructive button; label + optional icon | One dominant action per task group; rest, hover, focus, pressed, disabled, and loading are distinct |
| Enter information | Persistent label → field → help/error slot | Appropriate native type, autocomplete/input mode, required indication, preserved input, error association |
| Pick one | Native select for a conventional list; radio group for a short comparison | Legend/label, one selected value, native keyboard behavior; selected is more than color |
| Pick several | Checkboxes grouped under a legend | Independent choices; no preselected consent; indeterminate only for a real mixed group |
| Apply a setting immediately | Switch with a stable setting label | Use only for an immediate reversible setting; checkbox when the choice waits for submission |
| Change a view | Tabs for peer panels; links for routes; radios for a value | Real tabs use arrow/Home/End navigation, one tab stop, associated panels; manual activation if loading is slow |
| Reveal detail | Disclosure/accordion: heading + trigger + related content | Enter/Space toggles; `aria-expanded` for custom triggers; collapsing preserves a sensible focus location |
| Open navigation choices | Navigation disclosure with ordinary links | Click/touch/keyboard work; hover may preview; Esc dismisses and restores trigger focus; no application-menu role for site links |
| Explain a control | Visible help, or a dismissible popover | Tooltip only for supplementary text; touch has an equivalent; interactive help uses a popover, not a tooltip |
| Confirm or inspect | Dialog: title → explanation/content → actions | Native modal or established host primitive; focus contained, background inert, Esc/close when safe, focus restored |
| Compare or scan | Ruled list/table; card only for a cohesive object | Table caption and headers, stable reading order, responsive access to every value; no whole-card click with nested actions |
| Locate within content | Breadcrumbs, chapter index, pagination | Labeled navigation; current item explicit; pagination uses real links and keeps filters; long ancestors may collapse accessibly |
| Show identity/state | Avatar, badge, or removable chip | Avatar fallback preserves the name; badge is status text; chip has a named remove action and keyboard focus recovery |

A search field has a visible label, `type="search"`, a clear action when nonempty, and distinct no-results/failed-search states. A file field exposes accepted types and limits before selection; progress, rejection, retry, and removal belong to each item. Use native date/time controls where appropriate and disclose time zone; numeric fields declare supported ranges. Password/account fields allow password managers and paste, expose a named visibility action where provided, and never confirm persistence before the response.

Dialogs use a 28rem short-decision or 40rem review width, bounded by viewport insets; long bodies scroll inside the dialog while title and actions remain reachable. On mobile, the inset and layout adapt to the available viewport. The decision names the object, consequence, and reversibility. Reversible low-risk actions may use Undo after success; consequential actions require review; only catastrophic actions require typing an exact identifier. Focus the safe action for destructive decisions. Admin dialogs retain Workbench's sizes.

### 5.13 State and feedback contract

| State | Visual and behavioral rule | Accessible / recovery rule |
|---|---|---|
| Rest | Action and label identifiable without hover | Correct native role and accessible name |
| Hover | Subtle color/surface change in 160ms; no target movement | No information or action available only here |
| Focus | Immediate visible ring, independent of selection | Use `:focus-visible`; never clip or obscure it |
| Pressed | Acknowledgment within 100ms; optional scale 0.98 | Keep hit area stable; no displacement under reduced motion |
| Disabled | Reduced emphasis plus explanation of the prerequisite | Native disabled when inoperable; `aria-disabled` only with activation actually blocked |
| Read-only | Value remains legible and selectable | Explain why editing is unavailable; do not style it as missing |
| Loading | Preserve control size, entered values, and useful old content | Mark the updating region busy; prevent duplicate submission; announce meaningful progress once |
| Empty | Explain the object and one next step | Separate first-use empty from no matching results |
| Error / offline | Inline effect and recovery, including preserved work | Associate field errors; focus an error summary or first invalid field on failed submission |
| Success | Confirm the actual result briefly | Announce once after confirmation; keep a persistent receipt for consequential work |
| Permission-limited | Explain unavailable action without exposing protected data | Offer sign-in or access request only when supported; never imply authority |
| Approval | Source, scope, impact, and explicit confirming verb | No preselected consent; no inferred authorization from inactivity |

Use **inline feedback** for a persistent condition or field issue, **a banner** for a page-wide interruption, **a toast** for a transient confirmed result, and **a dialog** for a required decision. A toast must not be the sole record of a failure, approval, or receipt. Keep action-bearing feedback reachable until acted on or dismissed. Routine announcements use `role="status"`; urgent failures may use `role="alert"`; avoid duplicate toast and inline announcements for the same event. Static examples are ordinary labeled content, not a page full of live regions.

For loading, a skeleton matches the expected layout and is hidden from assistive technology; its parent names the pending work. Use a determinate progress bar only when progress is known. Otherwise name the current step without inventing percentages. A step list distinguishes pending, running, complete, and failed, with one terminal result. Loading motion stops under reduced motion and retains a text explanation.

## 6. Copy and terminology

Cedros speaks like a capable colleague: plain, confident, warm, specific, and calm.

| Attribute | Means | Not |
|---|---|---|
| Plain | Everyday words, active voice | Jargon and abstractions |
| Confident | Direct facts and outcomes | Swagger or false certainty |
| Warm | Human phrasing and contractions | Cute, jokey, or overfamiliar |
| Specific | Names the object and consequence | Vague "something" copy |
| Calm | Stable temperature in success and failure | Alarm or celebration spam |

The user is "you." The system is "Cedros." Cedra may use "I" in chat. Use "we" only where humans plausibly stand behind the words.

### 6.1 Parent-brand language

Prefer: website, business, customer, content, commerce, question, answer, follow-up, support, workflow, business knowledge, approved information, human review, working part of the business.

Use carefully after benefits are clear: AI, agent, automation, operating surface, agent-native, structured knowledge, permissions, MCP, autopilot.

Do not lead with Solana, crypto, blockchain, tokenization, onchain, wallets, x402, Rust, frameworks, protocol language, or commerce OS.

### 6.2 Headlines and CTAs

Use one idea per headline, outcome before capability, short body blocks, and active voice. Do not create a new slogan in every section or repeat the same feature inventory.

CTA labels use a verb or verb + object: "Start building," "See the platform," "Publish," "Approve and send." Match actual availability. Use "Join the waitlist" when onboarding is closed. Never create dead actions.

### 6.3 AI language

Prefer: uses approved knowledge, prepares the next step, needs your review, allowed to publish, allowed to prepare but not send, ask before changing, completed and recorded, handed to a person.

Avoid: magic, limitless, fully autonomous, runs itself, replaces your team, human-free, revolutionary, seamless, supercharge, unlock, leverage, utilize.

### 6.4 State copy

Error formula: what happened → effect on the user's work → next step.

> Cedros couldn't finish this request. Your draft is safe. Try again; if it keeps happening, contact support with code `req_8f3a`.

Loading names the work after 1 second. For work over 10 seconds, say whether leaving is safe. Success names the outcome and omits "successfully."

Destructive copy names the object, exact consequence, scope, and reversibility. Title and button use the same verb and object.

### 6.5 Terminology

| Use | Meaning | Avoid |
|---|---|---|
| Delete | Permanent removal | Remove as euphemism |
| Archive | Recoverable removal from active lists | Delete when history remains |
| Remove | Take out of a place while it exists elsewhere | Permanent removal |
| Uninstall | Extensions | Remove extension |
| Extension | Cedros add-on capability | Plugin, module, add-on |
| Website | Public category and marketing | Web site |
| Site | The user's specific site in product UI | Website when the shorter term is clearer |
| Sign in / Sign out | Authentication | Log in/out; Login as verb |
| Publish / Unpublish | Public visibility | Deploy outside technical surfaces |
| Turn on / Turn off | Toggle prose | Activate/deactivate |
| Connect / Disconnect | Services and domains | Vague "integrate" |
| Choose | Human-facing selection | Select when choose is clearer |
| People / Customers | CRM humans | Contacts or leads as universal nouns |

### 6.6 Mechanics

Sentence case. Use …, numerals, tabular data, locale-aware formatting, and no emoji in product UI. Exclamation marks are reserved for rare milestones. All user-facing strings use the existing i18n system; avoid concatenated sentences and support RTL/text growth.

## 7. Motion and interaction

### 7.1 Registers

Workspace motion explains state quickly. Brand motion explains relationships through architecture, environment, and product narrative. Never apply cinematic timing to controls or workspace timing to an environmental reveal.

### 7.2 Timing

Workspace base timing follows current `--motion-*` tokens. Workbench §9 owns its component-specific bindings (including 180/120ms menu and 400/200ms toast entry/exit); those bindings are deliberate exceptions to the base scale, not a second public catalog:

| Use | Duration |
|---|---|
| Press and micro-state | 100ms |
| Hover, fade, exit | 160ms |
| General panel, disclosure, view change | 220ms |
| Dialog entry | 240ms |
| One-time metric/chart | 500ms |
| Update highlight | 800ms |

Brand guidance:

- Editorial reveal: 450–900ms
- Product transition: 500–1200ms
- Architectural reveal: 800–1800ms
- Environmental loop: 8–24s, subtle and nonessential
- Scroll narrative: progress-driven and interruptible

Longer is not better. Nothing bounces. Focus visibility is instant.

### 7.3 Signature patterns

- **Architectural reveal:** masks, apertures, sectional cuts, sliding planes.
- **Flow:** a sparse line carries context or work to a meaningful destination (the progress spine beside a request's steps; the section line down through the operating surface).
- **Resolve:** product state settles into an inspectable final condition.
- **Environmental depth:** layered media, surface-aware lighting, and small parallax create place. Image-based relief may respond to the pointer while text and controls remain stable. Keep the approved image as the fallback; stop rendering when idle or out of view.
- **Cedar-ring aperture:** concentric geometry reveals a layer or permission boundary.
- **Editorial reveal:** lines or semantic groups enter with restrained clipping or focus.

Motion should make a relationship or state change legible: entrances converge on a shared surface, an approved fact reaches its outputs, a reviewed request resolves into work. Interactive examples respond immediately and remain usable while the explanatory motion settles. Avoid random motion, bounce, cursor trails, continuous product movement, and animation added only because an element entered the viewport. Viewport reveals hold their first frame only for scenes below the fold at mount, start as the leading edge crosses roughly 88% of the viewport, release when focus lands inside them, and fail open: a scene already on screen never animates, and an observer that reports nothing once the page is visible releases every held scene.

### 7.4 Scroll and pointer

Use native scroll. Budget motion by the relationships the page needs to explain, not a quota of animated sections. Give each scene one clear interaction and a stable resting state.

Pin a section only when the scroll changes the composition itself. A list that fills in row by row, or a diagram that fades in, does not earn 300vh of friction; show it at once. Pinned sections that remain need meaningful progression, a clear exit, and a simpler mobile alternative. Never alter wheel speed or create long blank intervals.

Pointer response is sparse: a few pixels of image relief, material-aware lighting, or a restrained route response. Text, controls, and their hit targets stay still. Never replace the cursor, tilt every card, move text toward the pointer, or hide information behind hover.

### 7.5 3D and WebGL

Use 3D for environmental or architectural depth: layered planes, terrain sections, apertures, restrained camera movement, and light moving through channels.

Avoid glossy spheres, chrome objects, orbiting UI, particle-heavy fields, and simultaneous continuously rendering canvases. Several image scenes may share the same relief treatment, but only visible, interacting scenes render. Use WebGL only when it is materially better than DOM, SVG, and layered media. Cap DPR, pause offscreen rendering, clean up resources, and provide still fallbacks.

### 7.6 Reduced motion and performance

Reduced motion removes scrubbed camera movement, parallax, and nonessential loops; substitutes short fades; renders final product states; and preserves content, chat, and CTAs.

Every input acknowledges within 100ms. Navigation shows content or a skeleton within 300ms. Typing remains jank-free. Animate transform and opacity where practical, avoid large animated filters, pause offscreen media, and remove persistent `will-change`.

### 7.7 Public motion recipes

These are design bindings for public surfaces, not new theme manifest fields. Standard easing is `cubic-bezier(0.16, 1, 0.3, 1)`; exit easing is `cubic-bezier(0.4, 0, 1, 1)`. Brand timings select a bounded value from §7.2; the board uses 720ms editorial, 900ms product, and 1400ms architecture. Workspace bindings remain in Workbench.

| Pattern / trigger | Movement and timing | Lifecycle / reduced motion |
|---|---|---|
| Control feedback / pointer or activation | Color/surface 160ms; optional press scale 1 → 0.98 in 100ms, origin center | Reverse from current value on release; focus instant; no scale under reduced motion |
| Navigation disclosure / explicit open | Fade + y −4px → 0; 180ms standard in, 120ms ease-in out; origin at trigger | Closing interrupts opening; trigger and hit area stay still; reduced: immediate visibility |
| Dialog / explicit open | Fade + y 8px → 0, scale 0.98 → 1; 240ms standard in, 160ms ease-in out | Focus behavior never waits for animation; reduced: immediate final state |
| Accordion / toggle | Content fade 160ms; optional measured height change ≤220ms | Essential answer available immediately; rapid toggles reverse; reduced: no height animation |
| Tabs / selection | Indicator 220ms standard; optional panel crossfade 160ms | Update selected semantics immediately; no wait for distant panels; reduced: immediate selection |
| Confirmed feedback / response | Inline text crossfade 160ms; public toast fade + y 8px → 0, 220ms in / 160ms out | One arrival per event; no repeat on rerender; reduced: static receipt |
| Editorial reveal / first meaningful appearance | Clip line group while translating text y 12px → 0; 720ms standard | Once per scene, never on back navigation; no essential copy hidden before enhancement; reduced: text visible |
| Product resolve / selected state | Fade 0.35 → 1, y 16px → 0, scale 0.97 → 1; 900ms standard | Interaction acknowledges immediately; final content remains inspectable; reduced: final state |
| Architecture / deliberate exploration | Reveal mask bottom 68% → 0, or flow line scaleX 0 → 1 from its source; 1400ms standard | One relationship; reset/replay only on explicit input; reduced: complete diagram |
| Environmental depth / pointer | Decorative planes move at most 8px; settle ≤1400ms standard | No text or control movement, no required hover; touch and reduced: original still |
| Permission geometry / explanation | Inner rings rotate at most 18° / −24° over 900ms; restrained border emphasis | Decorative explanation cannot indicate actual consent; reduced: static rings and explicit state text |

Never queue animations behind repeated input. A new selection replaces the current transition from its present visual state; route changes cancel pending work. On first-entry groups, stagger by at most 45ms with a total added delay no greater than 180ms; headings and controls do not wait behind a sequence. Do not replay introductions on history navigation, filtering, refetch, or theme changes.

Nonessential automatic loops default off. If a loop is justified, provide a visible pause/stop control, stop offscreen and when the document is hidden, and disable it for reduced motion. Never use a loading animation to imply server progress. The board demonstrates explicit checkbox replay, with every resting state readable; uncheck to reset, then check to replay. Its CSS demonstrations are not production permission, submission, or navigation behavior.

## 8. Chat-first public experience and homepage

### 8.1 Principle

Chat is another interface to the same Cedros system, not a disconnected support bot. Anything shown as possible through chat must use the same context, permissions, tools, and records as conventional UI, or be clearly labeled as a demonstration.

The public assistant may explain Cedros, receive a business description, show a relevant example, navigate the site, and begin onboarding. It must not block normal navigation.

### 8.2 Hero requirements

The flagship Cedros homepage keeps cinematic campaign imagery tied to the website-and-assistant relationship, makes “a website with an AI assistant built in” explicit in its lead, and includes:

- H1: Websites that think, act, and work for you.
- A clear conversation button opening a dedicated assistant page
- An explicit label such as “Talk to Cedros,” shared by the hero and closing entry
- A conventional exploration path for visitors who want to read first
- Official Cedros identity
- Conventional sign-in and acquisition paths
- A dedicated mobile composition

Give conversation its own quiet page: a back link, truthful assistant state, readable thread, and composer. Use “What are you building?” as the opening prompt and the locked placeholder from §1. Suggestions prepare editable drafts. Keep the composer visible as the thread grows and the mobile keyboard opens.

Keep the homepage focused on its promise, campaign image, and conversation entry. Do not embed a competing chat panel or floating chat dock. Do not use audience tabs, a white bordered hero card, a dashboard collage, knowledge sphere, orbiting cards, corner bubble, or fake autoplay conversation.

### 8.3 Conversation states

| State | Required behavior |
|---|---|
| Idle | The conversation page offers the opening prompt, composer, suggestions, and checked availability |
| Focused | One clear input focus indicator; the mobile keyboard does not cover the send control |
| Sending / responding | Real output, stable layout, accessible live region, cancel where supported |
| Clarification | One necessary question and clear reply path |
| Proposed action | Intended action, source, scope, and permission are visible |
| Approval required | Human decision is explicit; consent is not preselected |
| Complete | Outcome and record are visible; next step is clear |
| Error / offline | Input is preserved; retry and conventional routes remain |
| Navigation | A clear return path remains available; claim restored context only where implemented |

Do not hardcode fake streaming, imply protected anonymous actions, claim data was saved when it was not, or present a demonstration as real customer activity.

Check assistant configuration through a read-only request before claiming readiness. Checking, unknown, unavailable, and human-only modes are distinct; a readiness check never creates a conversation or invokes AI. An unsupported readiness check is not a failed message: keep uncertainty visible without opening a recovery banner before the visitor acts. Configuration readiness is not proof of provider uptime. Claim a recorded conversation only when the response confirms persistence.

### 8.4 UI and chat parity

The strongest proof shows the same supported action performed through conventional UI and chat, resolving to the same state. Keep the result stable while the input method changes.

### 8.5 Narrative composition

Lead with a recognizable benefit, establish the product through truthful evidence, answer adoption concerns, and leave a clear next action. Section order follows the visitor's questions and the capabilities the product can actually support. Exact sequence, composition, campaign assets, and tool-specific copy live in `design-cedros-examples.html#homepage`.

### 8.6 Product proof and composition

Each section answers one question. Prefer a few inspectable examples over a tour of every feature. Identify whether an object is a real capture, a design study, or illustrative data. Preserve the relationship between selected tool, caption, and inspectable result. Recommendations remain proposals until accepted; separate queues do not become a unified inbox through presentation. Specific app-window, foundation, and human-scene layouts belong in the examples document.

### 8.7 Campaign media

Campaign environments and documentary-style imagery may be generated with `gpt-image-2` through a secure local or server-side workflow (`scripts/homepage-media/generate.mjs`). Review, optimize, and ship them as static assets. The API key never enters the browser or repository.

Use real product components and captures for Cedros product evidence; label compatibility illustrations as described in §4.7. Maintain a media manifest (`custom-pages/homepage/MEDIA.md`, `assets/manifest.json`) with source, prompt/model where relevant, dimensions, focal point, text-safe area, loading priority, alt/decorative status, and approval state. Keep detailed asset tables in the implementation brief, not this standard.

### 8.8 Homepage anti-patterns

Do not ship:

- One rounded cream page around the site, in either mode, on any host bundle
- Repeated full-height white sections with little content
- Centered serif headline + card grid as the repeated section formula
- Orbiting nodes, knowledge spheres, interchangeable feature grids, or unreadable dashboard collages
- Glassmorphism, HUD, neon, cyberpunk, generic robot mascots, or particle spectacle
- Tiny unreadable screenshots, or captures cut mid-sentence
- Fake UI, metrics, customers, testimonials, logos, or assistant output
- Multiple 400–500vh scroll tracks, scroll hijacking, or custom cursors
- Coastal imagery that reads as luxury real estate or resort advertising
- Rows of pills, mono uppercase labels inside panels, or a kicker on every object

### 8.9 Homepage acceptance test

- **Brand:** recognizably Cedros without the logo; dark Pacific, architectural, editorial, operational, human; not resort, cyberpunk, or generic AI.
- **Clarity:** website category understood in 5 seconds; useful-work promise in 10; legible product proof appears early.
- **Chat:** real, immediate, accessible, truthful; dedicated entry, error, offline, retry, and return navigation work; approval and restoration are shown only where supported; ordinary navigation remains.
- **Product:** supported UI only; request becomes a permissioned and recorded result; UI and chat share state; human control is visible.
- **Composition:** fewer stronger ideas; no card grid drives the narrative; media, product, copy, and motion belong together; mobile is authored.
- **Engineering:** no dead routes, fake output, exposed secrets, console errors, leaks, failed tests, or reduced-motion gaps; shared-theme routes are regression checked.

## 9. Implementation and review

### 9.1 Architecture

- Use semantic tokens; do not scatter themed literals.
- Keep neutral kernel and Cedros marketing preset separate.
- Extend existing primitives before forking.
- Keep one-off page choreography out of shared components.
- Keep major copy and media in existing configuration/content systems where practical.
- Resolve the active owner of a route before editing. Extension-owned pages are authored and released through their owning extension; an older custom-page draft is not evidence of what the route serves.
- Do not create one monolithic homepage component.

### 9.2 Secure image generation

When an OpenAI key exists in `.env`:

- Use it only in a local script, protected server task, or build-time utility.
- Never log, commit, expose, or ship it.
- Use `gpt-image-2` for campaign art and edits, never product UI.
- Generate a small candidate set, select deliberately, and use approved outputs as references for related assets.
- Record model, prompt, date, dimensions, format, and edit lineage without secrets.
- Optimize selected files before shipping.
- Never call the image API from the public page at runtime.

### 9.3 Product capture

Verify the capability and route, seed believable nonprivate data, remove credentials, capture whole cards at a useful resolution, keep text legible, and label demonstrations. Do not show broken or placeholder states as finished proof.

### 9.4 Review sizes

Review at minimum:

- 1728×1117
- 1440×900
- 1280×800
- 1024×768
- 768×1024
- 430×932
- 390×844
- 360×800

Also test wide desktop, mobile keyboard-open, 35% text growth, and representative RTL where localized.

### 9.5 Required checks

- **Performance:** critical H1, navigation, and primary action render before nonessential media; the dedicated conversation page prioritizes its composer; only critical assets preload; responsive modern images; posters for video; below-fold lazy loading; offscreen pause; capped WebGL DPR; no layout shift or hydration mismatch; typing remains responsive; effects clean up.
- **Accessibility:** semantic landmarks and heading order; AA contrast; keyboard completion and visible focus; touch parity; correct names/roles/live regions; no critical text in imagery; no hover-only information; accessible chat errors, retry, loading, and approval; complete reduced motion; localization survives.
- **Copy:** locked hierarchy, outcome before capability, sentence case, no AI hype or headcount framing, real CTA availability, exact error/destructive copy, terminology respected, i18n used, no invented evidence.
- **Motion:** correct register, one main motion idea per section, native scroll, earned pinned length, product resolves and stops, pointer effects nonessential, reduced motion complete, smooth on ordinary hardware.
- **Theme regression:** inspect the homepage, a standard content page, form-heavy page, commerce/product page, desktop/mobile navigation, and one representative customer/generated site. Review light and dark. Confirm there is no wrapper frame, inset, or radius around the homepage at any breakpoint, in either mode, and under a host bundle that predates the `canvas` surface (the publish tool's legacy-shell path).

### 9.6 Validation and evidence

Run formatting, lint, type checking, unit/component tests, end-to-end tests, and production build. Test navigation, sign in, signup/onboarding, assistant questions, clarification, approval, error/retry, mobile keyboard, reduced motion, slow network, and failed media.

Capture before/after screenshots and review them at actual viewport size. Fix issues rather than only documenting them.

A major public design PR should include:

- Summary of theme and page changes
- Components created, removed, or materially changed
- Routes checked for regression
- Before and after screenshots
- Live versus demonstration assistant behavior
- Product captures and generated media used
- Media manifest and generation-script paths
- Performance and accessibility decisions
- Commands and results
- Genuine remaining limitations

### 9.7 Standing boundaries

- `design-admin.md` wins inside `/admin`.
- Customer themes retain their own identity.
- `--cedros-*` and `--cds-*` remain separate.
- Payment-provider brand colors remain where required.
- Existing i18n architecture remains the source for user-facing strings.
- Legacy surfaces align on touch unless a scoped migration is commissioned.
- Crypto, tokenization, and developer capabilities live on appropriate deeper surfaces, not as the parent homepage story.

### 9.8 Runtime boundary and coverage

The public token compiler and preset are the current implementation references (§4.10). Public navigation behavior is shared by `ui/src/site-templates/publicNavigationDropdowns.ts`; forms use the owning public form runtime. Reuse those paths before extending a primitive. Generated public class names are namespaced, so board classes are never a runtime selector contract.

**Host availability:** component sizes, motion recipes, accessible overlay behavior, and data conventions in this standard define acceptance criteria. They do not claim that every existing public renderer already implements them. Verify the actual primitive, supported token, and call site before implementation. Missing runtime support requires a scoped implementation change; do not document a speculative export, manifest field, or callback as available. The static dialog, feedback, code, and chart specimens show anatomy; native fields, radios, disclosures, and replay controls demonstrate only their stated local interactions.

### 9.9 Accessibility and input contract

Follow [WCAG 2.2 AA](https://www.w3.org/TR/WCAG22/). Normal text needs 4.5:1 contrast; large text and necessary control boundaries/state indicators need 3:1 where applicable. Heartwood sets a 44px public control target, above the AA minimum; inline prose links retain their native text flow. Check contrast on the actual surface, including media and both modes.

- Provide landmarks, one descriptive H1, ordered headings, and a working skip link. Anchored headings clear sticky navigation and receive programmatic focus. Focus must stay visible as menus, dialogs, and virtual keyboards change the viewport.
- Native inputs retain browser keyboard behavior. Composite widgets follow their semantic pattern: arrow keys within radio/tab/menu groups; Esc dismisses only the topmost overlay and returns focus to its trigger. Site navigation uses links, not application menu semantics. Never trap focus outside a modal.
- On modal open, place focus at the title or appropriate first control; contain focus and make the background inert. Restore focus to the invoker or a logical successor if the invoker was removed. Do not focus a destructive action by default. Custom CSS overlays without these behaviors are not dialogs.
- Associate every field label and help/error message. On failed submit, preserve values, identify errors, and focus the summary or first invalid field. Announce state changes once (§5.13); streaming chat uses coherent updates, not per-token speech.
- At 200% text zoom and a 320 CSS-pixel viewport, preserve content and actions without page-wide horizontal scrolling. Tables/code may scroll within a labeled, keyboard-accessible frame. Test text spacing overrides and 35% translated-text growth. Use logical properties; mirror directional navigation where appropriate, not logos or data.
- Reduced motion shows complete content and final product states, not merely faster transitions. Pause automatic moving content; provide alternatives for pointer exploration. Media has purposeful alt text or is decorative, and meaningful video/audio has an accessible text/caption alternative.

### 9.10 Pair acceptance checklist

- [ ] Markdown and HTML share version, scope, semantic role values, scales, recipe names, and state vocabulary.
- [ ] HTML shows foundations, public components, feedback states, data/technical content, access, and motion; Markdown explains each family.
- [ ] Native specimen controls work with keyboard and touch; static anatomy is explicitly labeled and never implies a completed action.
- [ ] Light/dark, narrow layouts, focus, reduced motion, empty/loading/error, disabled/read-only, and approval paths are represented.
- [ ] Public APIs and tokens resolve to current source; desired behavior is distinguished from host availability.
- [ ] Page-specific narratives and full-page layouts remain in `design-cedros-examples.html`.
- [ ] Both files change together and carry a brief changelog. Source-built authoring kits include them; immutable release archives change only through the documentation release process.

## Appendix A — quick token reference

```css
/* Workspace core: current host values remain canonical */
--cd-bg;
--cd-card-bg;
--cd-fg;
--cd-muted;
--cd-muted-bg;
--cd-border;
--cd-accent;       /* surface, never text */
--cd-primary;
--cd-primary-fg;
--cd-ring;
--cd-success;
--cd-warning;
--cd-info;
--cd-error;

/* Historical brand reference notation; public runtime mapping is §4.10. */
--cd-brand-obsidian: #0D0D0E;
--cd-brand-ink: #07111F;
--cd-brand-bone: #F6F5F2;
--cd-brand-paper: #FFFDF7;
--cd-brand-cream: #FAF6EA;
--cd-brand-stone: #D9D7D2;
--cd-brand-slate: #6E6E72;
--cd-brand-moss: #3F5A4A;
--cd-brand-oxidized: #315B59;
--cd-brand: #2F6C7D;
--cd-brand-bronze: #B48755;
--cd-brand-rust: #9B5B3F;
--cd-gold: #E8BE75;

/* Type (shipped by the marketing publish as site media) */
--cd-font-sans: "IBM Plex Sans", "Avenir Next", "Segoe UI", sans-serif;
--cd-font-serif: "Newsreader", "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
--cd-font-mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;

/* Public layout */
--cd-gutter: clamp(1rem, 3vw, 3rem);
--cd-section-space: clamp(4.5rem, 10vw, 10rem);
--cd-section-space-compact: clamp(3rem, 6vw, 6rem);
--cd-reading: 68ch;
--cd-content: 76rem;
--cd-wide: 100rem;

/* Workspace motion */
--motion-duration-micro: 100ms;
--motion-duration-fast: 160ms;
--motion-duration-standard: 220ms;
--motion-duration-modal: 240ms;
--motion-duration-counter: 500ms;
--motion-duration-highlight: 800ms;
--motion-ease-standard: cubic-bezier(0.16, 1, 0.3, 1);
--motion-ease-in: cubic-bezier(0.4, 0, 1, 1);
```

## Changelog

- **v2.18 — 2026-09-08.** Complete public foundations, component/state contracts, data conventions, accessibility, and motion recipes with matching HTML specimens. Separate page composition from reusable guidance and clarify public token ownership and Workbench motion precedence.

- **v2.17 — 2026-09-07.** Align shared navigation, dark surface contrast, stable product selection, responsive inspection, and optional image relief. Add detailed product, pricing/program, and contact-page contracts. Correct identity availability and retire outdated hero-composer and assistant-mechanics requirements.

- **v2.16 — 2026-09-06.** Explain the website-platform requirement and distinguish new builds, code adaptation, and supported content migration.
- **v2.15 — 2026-09-06.** Make familiar customer access, owner control, and optional AI adoption explicit. Human scenes support separate decisions, without fabricated product overlays.
- **v2.14 — 2026-09-06.** Separate website craft from feature breadth. Make reusable infrastructure explicit, remove redundant task outputs, and distinguish incoming-work context from proactive recommendations.
- **v2.13 — 2026-09-06.** Establish platform substance and reusable foundations before assistant mechanics. Favor meaningful example outputs and source-backed recommendations; allow asymmetric product evidence with readable captures.

- **v2.12 — 2026-09-06.** Give conversation a dedicated page, reached through clear homepage entry buttons. Keep readiness and recovery inside that page.
- **v2.8 — 2026-09-06.** Allow recognizable workspace illustrations to explain compatibility, with truthful connection scope and stable selection controls. Distinguish these illustrations from real product evidence.

- **v2.7 — 2026-09-06.** Require campaign images to explain themselves without copy; permit a legible living-website metaphor. Clarify draft suggestions and readiness uncertainty.
- **v2.6 — 2026-09-05.** Preserve cinematic campaign imagery while tying it to the business and product. Make the website-and-assistant package explicit; keep real screen captures separate from generated surroundings.
- **v2.5 — 2026-09-05.** Bring inspectable product proof forward; give each section one question and a composition suited to its information. Require useful, clearly labeled example controls, concrete shared-context outputs, progressive capability detail, and motion that explains relationships.

- **v2.4.1 — 2026-09-05.** Require read-only assistant readiness checks, distinguish unknown and unavailable states, and tie recording and undo claims to verified behavior. Commerce positioning does not establish a shipped checkout.

- **v2.4 — 2026-09-05.** Positioning rewritten around the two-sides-of-the-market narrative: one authoritative operating surface on the domain, three ways in, one business state, agentic commerce as the first proof. Story order and homepage narrative follow it; examples must cross the system rather than illustrate trivia. Operating-surface environment regenerated as a true sectional cut.
- **v2.3.1 — 2026-09-05.** Chat must look like a conversation (header, opening prompt, inset field, prompt buttons). No pinned sections unless the scroll changes the composition; the request-to-outcome proof is a transcript, and the operating surface is an environment with strata. Split heads alternate with stacked heads; one photograph anchors at most two sections.
- **v2.3 — 2026-09-05.** Restored Markdown structure (headings, tables, code fences) lost in the v2.2 condensation. Type tokens now name the shipped brand fonts (Newsreader, IBM Plex Sans, IBM Plex Mono). Named where the official mark lives and the interim wordmark rule. Added the label budget, the pill prohibition, the ledger-over-boxes rule, whole-card capture rule, both-modes decision for the marketing preset, the homepage's own frame defense under legacy host bundles, composer visibility at rest, and the theme-regression check for the frame. The board now shows approved campaign assets and product captures instead of vector placeholders.
- **v2.2 — 2026-09-04.** Reduced the standard to durable brand, theme, chat, motion, homepage, and implementation rules. Removed duplicated page choreography, asset catalogs, and admin-component detail that belongs in the homepage prompt, media manifest, or `design-admin.md`.
- **v2.0–2.1 — 2026-09-04.** Added current positioning, living-infrastructure art direction, theme-kernel separation, chat-first public interface, real-product-proof requirements, and secure campaign-image generation.
- **v1.3 — 2026-08-20.** Established the previous Heartwood standard and Workbench relationship.

Heartwood v2.18 — maintain alongside `design-cedros.html`. Admin surfaces follow `design-admin.md`.