Molecule · stable · v1.0.0 · owner: Site system lead · contract 19 of 20 points (open: figma)
Do and don't
Do: A plan notice
Rendered by callout.tsOpen example: Callout · Do: A plan notice Use the full-page example to follow page links.
Do: A form error
Rendered by callout.tsOpen example: Callout · Do: A form error Use the full-page example to follow page links.
Don't: A sales message
Rendered by callout.tsOpen example: Callout · Don't: A sales message Use the full-page example to follow page links.
Don't: An error without a fix
Rendered by callout.tsOpen example: Callout · Don't: An error without a fix Use the full-page example to follow page links.
Rules
| Rule | Why | Check |
|---|---|---|
| At most one callout per section. | Two warnings compete and both get skipped. | Automated: scripts/site/system/check-pages.ts |
| An error says how to fix it. | An error that only says 'invalid' leaves the reader stuck. | Review: Content owner |
API
| Prop | Type | Required | Default | What it does |
|---|---|---|---|---|
kind | notice | info | error | No | "notice" | Notice for plans and limits, info for notes, error for form errors. |
html | html | Yes | The message. | |
title | string | No | A bold lead ('Coming next.'). |
Contract details
The full contract: identity, anatomy, variants, states, tokens, layout, motion, accessibility, content, tests
Identity
| Aspect | Value |
|---|---|
| Id | callout |
| Layer | Molecules |
| Category | feedback |
| Owner | Site system lead |
| Status | stable |
| Version | 1.0.0 |
| Source | apps/showcase/site/system/molecules/callout.ts (private repository; the contract and the render function are this one module) |
| Version | Date | Change |
|---|---|---|
| 1.0.0 | 2026-10-26 | Notices, information and errors on a soft ground with a top rule. |
Use when
- A demo shows a plan with sample data. Why: The reader must know it is not built before they try it.
- A form has errors. Why: The form owner lists errors at the top and links them to their fields; this component supplies only static message markup.
Do not use when
- For marketing emphasis. Why: Callouts that sell train readers to skip the ones that warn.
- More than one per section. Why: Two warnings compete.
Anatomy
| Part | What it is |
|---|---|
| root | p.callout with a top rule and a soft dye ground. |
| title | A bold lead. |
| body | The message. |
Made of: text, tokens:colour.
Used in: form-field, autonomy-demo, prose-section.
Variants
| Variant | When | Why |
|---|---|---|
| notice | A plan, a limit, sample data. | Saffron soft ground: attention, not alarm. |
| info | A neutral note (the health check's deep section). | Indigo soft ground: information. |
| error | Form errors. | Madder: something must be fixed. |
States
| State | Rendered or not applicable |
|---|---|
| default | default |
| hover | Not applicable: A callout is not interactive, so it has no hover state. |
| focus-visible | Not applicable: A callout does not take focus; links and buttons inside it carry their own focus ring. |
| active | Not applicable: A callout cannot be pressed. |
| disabled | Not applicable: A callout has nothing to disable. |
| loading | Not applicable: A callout is rendered at build time and is complete when the page loads. |
| empty | Not applicable: A callout is not rendered without content; the builder skips it. |
| error | The error variant. |
| current | Not applicable: A callout has no current item. |
| visited | Not applicable: A callout is not a link. |
| expanded | Not applicable: A callout does not open or close. |
Tokens
| Part | Token |
|---|---|
| root.background@notice | --saffron-soft |
| root.background@info | --indigo-soft |
| root.background@error | --madder-soft |
| root.border-top | --rule in the variant's dye |
| root.font | --type-small |
| --callout-padding-space-5 | var(--space-5) |
| --callout-padding-space-6 | var(--space-6) |
| --callout-background-surface-2 | var(--surface-2) |
| --callout-border-top-rule | var(--rule) |
| --callout-border-top-ink | var(--ink) |
| --callout-font-type-small | var(--type-small) |
| --callout-callout-rule-saffron | var(--saffron) |
| --callout-background-saffron-soft | var(--saffron-soft) |
| --callout-callout-rule-madder | var(--madder) |
| --callout-background-madder-soft | var(--madder-soft) |
| --callout-callout-rule-indigo | var(--indigo) |
| --callout-background-indigo-soft | var(--indigo-soft) |
| --callout-border-top-madder | var(--madder) |
| --callout-margin-space-3 | var(--space-3) |
| --callout-padding-left-space-7 | var(--space-7) |
Layout
| Aspect | Value |
|---|---|
| max | --w-text |
| breakpoints | Required review at 390, 768, 1024 and 1440 px; execution is not implied by this declaration; full width of its column. |
| wrapping | Wraps. |
| textExpansion | Grows downwards. |
Spacing and rhythm
| Aspect | Value |
|---|---|
| internal | --space-5 by --space-6. |
| external | --space-7 below. |
| rhythm | At the top of the content it qualifies. |
Motion
| Aspect | Value |
|---|---|
| None | A message that moves is harder to read. |
Runtime and reuse
Render-only element; mount any registered child enhancements separately. Preserve required Site CSS, fonts, responsive and locale rules from nativeElement.
Accessibility passport
| Aspect | Value |
|---|---|
| role | paragraph; the form owner supplies any error-summary region |
| name | Its title |
| keyboard | Links inside are focusable. |
| focus | Not focusable itself. The form owner manages submit-error focus. |
| screenReader | Read in place. Submit-error announcements belong to the enclosing form. |
| contrast | Ink on each soft ground 12:1 or better. |
| target | Not a target. |
Content
| Slot | Length | Voice |
|---|---|---|
| html | 3 sentences | What it is, then what to do |
Good: “Coming next. This demo shows a plan with sample data. It is not built yet.”
Bad: “Amazing new feature!”
Japanese: Text comes from the page content; Japanese strings are reviewed per page (apps/showcase/site/loom/locales). Awaiting native review, as the banner on every Japanese page says.
Icons and illustrations
None: this element uses no icon or illustration of its own.
Decisions and exceptions
Usage
8 uses across the built pages (measured by npm run site:system).
Tests
| Aspect | Value |
|---|---|
| unit | tests/unit/site-system.test.ts: renders every do and don't example through the registry and checks the classes it owns |
| visual | Not yet: there are no screenshot baselines; the Library page is checked for sideways scroll at 1440 px by tests/site/system.spec.ts |
| a11y | tests/site/system.spec.ts: axe (0 serious or critical) on the element's Library page in light and dark |
| parity | scripts/site/system/check.ts: Library examples are rendered by the same render function the site imports |
Figma
not-yet: The Loom Site Figma library is the last stage of the plan; this element is not mapped yet.