Foundation · stable · v1.0.0 · owner: Site system lead · contract 18 of 20 points (open: usage, no owned-class occurrences in built pages or metadata-token references in built CSS; application declarations and executed coverage are separate; figma)
Reference
Source reference; not an executed check.
art:edge-master- Contexts: Library artwork reference alongside the native Woven edge specimen · Alternative kind: decorative · English alternative: "" (intentionally empty) · Japanese alternative: "" (intentionally empty) · Japanese review: not applicable (decorative)
art:edge-quiet- Contexts: Catalogue alternative; page adoption unverified · Alternative kind: decorative · English alternative: "" (intentionally empty) · Japanese alternative: "" (intentionally empty) · Japanese review: not applicable (decorative)
art:edge-corner- Contexts: Catalogue corner study; page adoption unverified · Alternative kind: decorative · English alternative: "" (intentionally empty) · Japanese alternative: "" (intentionally empty) · Japanese review: not applicable (decorative)
art:edge-end- Contexts: Catalogue end-piece study; page adoption unverified · Alternative kind: decorative · English alternative: "" (intentionally empty) · Japanese alternative: "" (intentionally empty) · Japanese review: not applicable (decorative)
art:spot-audit- Contexts: site pages; Library pages; articles; card headers; health check · Alternative kind: informative · English alternative: A magnifying glass over a woven swatch, showing one red square up close. · Japanese alternative: 織物の見本の上に虫眼鏡があり、赤い四角が拡大されている。 · Japanese review: AI draft, native review pending
art:spot-token- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: A swatch card with a blue colour block and two lines, and a yellow diamond beside it. · Japanese alternative: 青い色見本と2本の線が描かれたカードと、その横の黄色いひし形。 · Japanese review: AI draft, native review pending
art:spot-component- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: Four diamonds in blue, yellow, red and green arranged in a ring. · Japanese alternative: 青・黄・赤・緑の4つのひし形が輪のように並んでいる。 · Japanese review: AI draft, native review pending
art:spot-contract- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: A document with lines of text and a yellow seal with a check mark. · Japanese alternative: 文字の行が並ぶ書類と、チェックマーク付きの黄色い印章。 · Japanese review: AI draft, native review pending
art:spot-decision- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: A path from a blue dot splits in two: a solid line to a green card with a check, a dashed line to an empty card. · Japanese alternative: 青い点から道が二つに分かれ、実線はチェック付きの緑のカードへ、点線は空のカードへ続く。 · Japanese review: AI draft, native review pending
art:spot-exception- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: An hourglass with yellow sand beside a calendar page with one day marked in red. · Japanese alternative: 黄色い砂の砂時計と、一日だけ赤く印をつけたカレンダー。 · Japanese review: AI draft, native review pending
art:spot-review-queue- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: Three stacked cards, the front one blue, with a green check badge. · Japanese alternative: 3枚の重なったカード。手前の青いカードに緑のチェックバッジ。 · Japanese review: AI draft, native review pending
art:spot-ritual- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: Four coloured circles around a green round table, with two curved arrows going round. · Japanese alternative: 緑の丸いテーブルを囲む4つの色の円と、周りを回る2本の曲がった矢印。 · Japanese review: AI draft, native review pending
art:spot-agent- Contexts: site pages; Library pages; articles; card headers; agent sections · Alternative kind: informative · English alternative: A square blue weaving shuttle with pointed tips and a yellow bobbin, trailing a red thread. · Japanese alternative: 先のとがった四角い青い杼（ひ）。中に黄色い糸巻きがあり、赤い糸を引いている。 · Japanese review: AI draft, native review pending
art:spot-pull-request- Contexts: site pages; Library pages; articles; card headers · Alternative kind: informative · English alternative: Two blue nodes on a line and a green node joined back to it with an arrow, on a card. · Japanese alternative: カードの上に、線でつながった2つの青い点と、矢印で戻る緑の点。 · Japanese review: AI draft, native review pending
art:spot-health- Contexts: site pages; Library pages; articles; card headers; reports · Alternative kind: informative · English alternative: Four bars rising from left to right in red, yellow, green and blue. · Japanese alternative: 左から右へ高くなる赤・黄・緑・青の4本の棒。 · Japanese review: AI draft, native review pending
art:spot-certificate- Contexts: site pages; Library pages; articles; card headers; Academy · Alternative kind: informative · English alternative: A card with lines of text and a yellow rosette with red ribbons. · Japanese alternative: 文字の行があるカードと、赤いリボン付きの黄色いロゼット。 · Japanese review: AI draft, native review pending
art:state-empty- Contexts: empty and status panels on the site; interactive elements; product tour · Alternative kind: informative · English alternative: An empty spool with a dashed outline where the thread would be. · Japanese alternative: 糸が巻かれていない空の糸巻きと、糸の位置を示す点線。 · Japanese review: AI draft, native review pending
art:state-not-measured- Contexts: empty and status panels on the site; interactive elements; product tour · Alternative kind: informative · English alternative: A dashed square beside a yellow ruler. · Japanese alternative: 点線の四角と、その横の黄色い定規。 · Japanese review: AI draft, native review pending
art:state-error- Contexts: empty and status panels on the site; interactive elements; product tour; 404 · Alternative kind: informative · English alternative: A woven swatch with one red row breaking off into a loose thread. · Japanese alternative: 織物の見本から赤い一列がほどけて、糸が垂れている。 · Japanese review: AI draft, native review pending
art:state-done- Contexts: empty and status panels on the site; interactive elements; product tour · Alternative kind: informative · English alternative: A tightly woven blue swatch with a green check badge. · Japanese alternative: 目の詰まった青い織物の見本と、緑のチェックバッジ。 · Japanese review: AI draft, native review pending
placeholders- 5 recorded and never shown
Do and don't
2 positive / 2 negative authored documentation examples (2 each required); 1 reference (1 required); 0 failed. References and failures do not count; this is not behavior acceptance.
Do: A decorative edge stays silent
Authored by illustration.tsRendered consumer example; not an executed correctness check. woven-edge Isolated document follows the browser's colour and contrast preferences. The outer theme toolbar does not control this document.
Open example: Illustration · Do: A decorative edge stays silent Use the full-page example to follow page links.
Do: Finished spot art follows its own palette
Authored by illustration.tsRule illustration; not an executed check. illustration / art.palette
Finished governed spot art: cotton, ink, indigo, madder, saffron and teal; flat geometry with the recorded 2px ink line.
Use the existing asset record and its contexts, not a new image inferred from this example.Don't: An ungoverned colour enters the artwork
Authored by illustration.tsRule illustration; not an executed check. illustration / art.palette
<path fill="#ff00ff" d="…"/>
The source proposal introduces magenta, which is not in this illustration family's recorded palette.Don't: A placeholder presented as finished artwork
Authored by illustration.tsRule illustration; not an executed check. illustration / art.no-placeholders
A consumer selects an asset whose record still has placeholder: true and labels it finished.
No placeholder identifier or source file is referenced by this documentation example.Rules
| Rule | Why | Check |
|---|---|---|
| Illustrations use only the site palette. | A picture never brings a colour the tokens do not have. | Automated: scripts/site/assets/check.ts (palette) |
| No page references a placeholder. | Unfinished art must not ship. | Automated: scripts/site/assets/check.ts (placeholders) |
API
No props.
Contract details
The full contract: identity, anatomy, variants, states, tokens, layout, motion, accessibility, content, tests
Identity
| Aspect | Value |
|---|---|
| Id | illustration |
| Layer | Foundations |
| Category | foundation |
| Owner | Site system lead |
| Status | stable |
| Version | 1.0.0 |
| Source | apps/showcase/site/system/foundations/illustration.ts (private repository; the contract and the render function are this one module) |
| Version | Date | Change |
|---|---|---|
| 1.0.0 | 2026-10-26 | Illustration as one module: its markup moved out of the page builder (scripts/site) into the system. |
Use when
- The woven edge (art:edge-master) and empty or state moments. Why: Illustration marks the brand without competing with evidence.
Do not use when
- As decoration beside claims. Why: Real artefacts prove claims; drawings do not.
- A placeholder. Why: Placeholders are not finished work and must never ship.
Anatomy
| Part | What it is |
|---|---|
| set | apps/showcase/site/assets/illustrations/{edge,spot,state} |
| manifest | illustrations.json |
| records | apps/showcase/site/loom/illustrations/art-*.json |
| style | apps/showcase/site/loom/illustration-styles.json |
Made of: nothing (a base element).
Used in: pages directly.
Variants
| Variant | When | Why |
|---|---|---|
| light and dark | Every page, following the reader's setting. | The same roles resolve to light or dark values, so no element chooses its own. |
States
| State | Rendered or not applicable |
|---|---|
| default | The specimen. |
| hover | Not applicable: A foundation is not interactive. |
| focus-visible | Not applicable: Not focusable. |
| active | Not applicable: Not interactive. |
| disabled | Not applicable: Nothing to disable. |
| loading | Not applicable: Values are built into the stylesheet. |
| empty | Not applicable: The build fails if a value is missing. |
| error | Not applicable: Unresolved values fail the brand gate, not the reader. |
| current | Not applicable: No current item. |
| visited | Not applicable: Not a link. |
| expanded | Not applicable: Does not open. |
Tokens
| Part | Token |
|---|---|
| art.palette | cotton, ink, indigo, madder, saffron, teal (the site's Base steps, D-SITE-014) |
| art.line | 2 px ink |
Layout
| Aspect | Value |
|---|---|
| breakpoints | Required review at 390, 768, 1024 and 1440 px; execution is not implied by this declaration; columns stack under 768 px; the wrap keeps a 16 px gutter on phones. |
| wrapping | Text wraps; nothing scrolls sideways. |
| textExpansion | Japanese runs 20 to 40% longer; headings break between phrases (jaBreaks) and blocks grow downwards. |
Spacing and rhythm
| Aspect | Value |
|---|---|
| internal | Not applicable: a foundation has no box of its own. |
| external | Not applicable. |
| rhythm | Applies to every element that reads it. |
Motion
| Aspect | Value |
|---|---|
| None | A foundation does not move. |
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 | Not rendered on the site; its specimen in the Library is a list |
| name | The foundation's name |
| keyboard | Not interactive. |
| focus | Not focusable. |
| screenReader | The specimen is a plain list of names and values. |
| contrast | Every text and ground pair in the palette is checked (check-brand). |
| target | Not a target. |
Content
| Slot | Length | Voice |
|---|---|---|
| informative artwork alternative (asset record and consuming image) | Enough to convey the drawing's meaning; no separate numeric budget is declared | Use the record's English or Japanese alternative. An edge or a drawing repeating its adjacent heading is decorative and uses an empty alternative; do not embed words or numbers in the artwork. |
| art record summary (fixed Library specimen) | The native non-placeholder id, contexts, alternative kind, English/Japanese alternatives and Japanese review status; no editable content prop | Preserve the record's actual text and review status; intentionally empty decorative alternatives differ from missing informative wording. A drawing cannot prove a product result or turn a placeholder into finished work. |
Good: “art:edge-master with an empty alternative (illustrations.json marks it decorative)” · “English and Japanese alternatives in an informative drawing's record (manifest rule art.alt)”
Bad: “Woven edge repeated as spoken alt beside every decorative join” · “A product score written only inside an SVG drawing (manifest rule art.geometry)”
Japanese: Informative records require both English and Japanese alternatives; decorative records keep both empty. Put translatable explanation in surrounding text rather than inside the drawing. Preserve each record's Japanese review status; adding this guidance does not complete native review or artwork acceptance.
Icons and illustrations
-
art:edge-master
Decisions and exceptions
- D-SITE-011: One governed illustration set
- D-SITE-014: Base tokens are the single source of truth for the palette
Usage
0 owned-class occurrences in built pages plus metadata-token references in built CSS (measured by npm run site:system).
Application and coverage
Asset guidance (declared): The governed illustration manifest supplies palette, alternatives, contexts and placeholder policy to the asset checker. Its catalogue artwork is separate from the native 18px CSS woven edge: compose.ts inserts that edge at field/cotton joins and refuses touching fields.
Current check result: not assessed by this report. Declarations and source-file presence do not establish executed enforcement or accepted coverage.
Source authority and implementation (paths in the private checkout):
apps/showcase/site/assets/illustrations/illustrations.jsonscripts/site/assets/check.tsapps/showcase/site/system/compose.tsapps/showcase/site/system/styles/core/woven-edge.css
Declared rules and checks (not execution results):
art.palette: Illustrations use only the site palette. Automated check declared: scripts/site/assets/check.ts (palette)art.no-placeholders: No page references a placeholder. Automated check declared: scripts/site/assets/check.ts (placeholders)
Coverage still needed (not assessed here):
- Retain current-input palette, alternatives and placeholder-check results with negative asset canaries; independently check native field/cotton composition and unchanged edge geometry.
- Finished spot-art consumer evidence, context-appropriate alternatives, native-language review and V4 artwork/design-tool fidelity remain separate obligations; no decoration is added to raise usage.
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.