Decisions and exceptions

D-SITE-001: Loom Site is the site's own design system, governed by Loom

Decision

The marketing site's design system is Loom Site: tokens, atoms, molecules, organisms, templates and page declarations, each a module in apps/showcase/site/system with its contract (the 20-point matrix). The page builder composes only these modules. Records live in apps/showcase/site/loom.

Why

The site is Loom's best proof: if Loom can govern its own site, the claim that it governs a client's system is checkable. Before this, 30.2% of the site's rendered elements came from a defined system.

Consequences

• scripts/site/system/check.ts scores every element and the share of the site rendered from the system.
• scripts/site/system/check-pages.ts checks every page against its declaration.

D-SITE-002: A field is always followed by cotton; two fields never touch

Decision

A dye or ink field (indigo, madder, saffron, teal, ink) is always followed by cotton, and two fields never touch. The four-jobs band is one template (a grid of dye tiles inside the hero), so it counts as one field and is allowed.

Why

Two fields side by side blur into one block and the page loses its rhythm. The tiles of the four-jobs band are one piece of structure, not four sections, so the rule treats the band as one field.

Consequences

• The landing's problem section moved to cotton (madder is used only as marks there).
• The footer moved to cotton (D-SITE-009).
• The composer throws on two touching fields; check-pages verifies every built page.

D-SITE-003: The woven edge sits at every field/cotton join, and nowhere else

Decision

The woven edge (art:edge-master) sits at every join between a dye or ink field and cotton, in both directions, including the joins into and out of the footer, and nowhere else. Only the composer (apps/showcase/site/system/compose.ts) places it; templates never draw it. Thread: saffron next to a dye or ink field, ink next to saffron.

Why

The edge used once and then never again was the owner's first complaint. One rule, applied by one piece of code, is what makes it read as a system.

Consequences

• The edge inside the hero (between its head and the jobs band) was removed: both sides are fields.

D-SITE-004: Colour as structure, marks as state

Decision

Large fields carry section identity. Health and state are shown only by small marks, always with their word.

Why

A reader never has to decode a colour alone, and colour keeps one meaning per size.

Consequences

• check-brand and check-pages hold it.

D-SITE-005: One padding per template

Decision

Each template declares one vertical padding in its contract (point 9), from the section tokens.

Why

Templates that each chose their own padding made pages lurch between sections.

Consequences

• The spacing point of the matrix checks every template declares it.

D-SITE-006: Numbering only for the job sequence

Decision

Numbers appear only for the job sequence (See, Shape, Govern, Run: the four-jobs columns and the job sections).

Why

Numbers everywhere stop meaning order.

Consequences

• The counters on the Coming next cards, the transform-flow steps and the autonomy modes were removed.

D-SITE-007: One caption, with an honesty variant

Decision

Every figure, screenshot and showcase has a caption from the one Caption atom; sample, recorded or real data says so in its honesty variant.

Why

Fifteen caption styles made the site look unplanned, and a demo must never be mistaken for live client data (AGR-0001).

Consequences

• check-pages fails a figure without a figcaption.
• EX-SITE-001 covers the ix-*-caption classes until 30 Nov 2026.

D-SITE-008: One ShowcaseFrame for every self-playing element

Decision

Everything that plays or reacts sits in the Showcase frame, with one set of playback controls and its honesty caption.

Why

Readers learn that one frame means 'this runs'.

Consequences

• EX-SITE-003: older showcases still write the frame markup themselves until 30 Nov 2026.

D-SITE-009: The footer stands on cotton

Decision

The footer is cotton. The saffron call to action above it meets it with the woven edge.

Why

An ink footer under the saffron call to action made two fields touch.

Consequences

• Visible change: the footer is light instead of ink.

D-SITE-010: One governed icon set

Decision

The site uses only the 55 icons in apps/showcase/site/assets/icons, each with a record icon:; product Lucide icons map to them.

Why

One grid and one line weight; each icon has a recorded use.

Consequences

• scripts/site/assets/check.ts holds it.

D-SITE-011: One governed illustration set

Decision

The site uses only the illustrations in apps/showcase/site/assets/illustrations (art:); placeholders are never referenced.

Why

Unfinished or off-palette art must not ship.

Consequences

• art:edge-master is the woven edge's artwork.

D-SITE-012: Content tokens and one glossary

Decision

Repeated strings (calls to action, honesty captions, band names, job names) are content tokens; each concept has one term per language.

Why

Two words for one thing make readers think there are two things.

Consequences

• npm run site:copy checks it.

D-SITE-013: Japanese is a first-class locale

Decision

Every new string ships with its Japanese; Japanese pages carry the review banner until native review; layouts survive 40% expansion.

Why

Japanese readers are a launch audience.

Consequences

• Rationale beyond the owner's request was not recorded.

D-SITE-014: Base tokens are the single source of truth for the palette

Decision

Tokens, icons and illustrations use the same Loom Base steps: indigo dye-indigo.800 (#1e2a78), ink greige.900 (#17140f), cotton greige.25 (#f3eee3). The assets, which used dye-indigo.700, cotton.900 and cotton.25, were moved to these steps.

Why

Two slightly different indigos side by side looked like a mistake.

Consequences

• scripts/site/assets/check.ts checks the illustration palette against the site's values.

D-SITE-015: Headings break between whole words

Decision

Display headings break between words, and between phrases in Japanese (jaBreaks), never inside a word.

Why

A broken word in a display heading looks like an error.

Consequences

• None recorded yet.

D-SITE-016: Every rule has a why

Decision

Every rule in every contract states its reason and how it is checked. scripts/site/system/check.ts fails the build on a rule without a why.

Why

A rule nobody can explain gets broken or worked around.

Consequences

• None recorded yet.

D-SITE-017: The site's content rules are enforced

Decision

The 21 content and localisation rules in apps/showcase/site/loom/rules move from proposed to accepted. site:build runs scripts/site/check-copy.ts --strict.

• 17 rules had zero findings after the fixes and block the build on any new finding (severity error): banned words, British spelling, heading case, honesty captions, unbuilt claims, Japanese punctuation, the review note, Japanese spacing, name casing, colon reveals, competitor names, contractions, dashes, exclamation marks, savings figures, stock phrases and numbers with a source.
• 4 rules still have findings and report them on every build without blocking: "not X but Y" frames (44), future tense outside Coming next (16, each to be confirmed as describing what runs today), plain short sentences (9) and staccato triplets (4). Each blocks once its findings are fixed.

The owner-approved lines are allowlisted with the reason "owner-approved, 26 Oct": "Tools do not run a design system. People do.", "See it. Shape it. Govern it. Run it.", the hero line, and "The tools document. They do not repair." with the tool names.

Why

A rule that only reports gets ignored. A rule that blocks while it still has findings would stop every build. Blocking where the copy is clean, and reporting where it is not yet, makes every rule real today without hiding the remaining work.

Consequences

• Fixed on 26 Oct: 121 Japanese spacing issues, one set of Japanese job names (見える化する・整える・守る・運用する, glossary updated), one term for "scripted example" (スクリプトによる例), 下書き → ドラフト for system changes, one health-check label (無料のヘルスチェックを始める), "next-generation", 13 demo sections given an honesty caption, the status-chip text removed from voice.md.
• The remaining 73 findings are listed in reports/content-findings.md (npm run site:copy -- --write).

D-SITE-018: High contrast is a token mode

Decision

Loom Site has three colour modes: light, dark and high contrast. High contrast is Loom Base's own high-contrast mode (light based: black ink on white, deeper dyes for the fields, ink borders), generated into tokens.css by scripts/site/brand-tokens.ts and applied when the reader's system asks for more contrast (prefers-contrast: more). It wins over dark when both are asked for, because it is the stronger request.

Why

Readers who need more contrast should get it from the same roles every element already reads, without an element of its own changing. Using Base's mode keeps one source of truth for values (D-SITE-014).

Consequences

• tests/unit/site-contrast-modes.test.ts checks 13 text pairs in each mode: 4.5:1 in light and dark, 7:1 in high contrast. All pass.
• The exported tokens carry the high-contrast context, so Loom's audit sees the mode.
• There is no in-page switch; the mode follows the reader's system setting. A switch would be a separate decision.

D-SITE-019: V4 identity, break and repair, and the supporting family

Decision

Adopt the V4 identity playground and eight-frame break-and-repair direction. Carry forward logo assembly, the sticker family, hero/drift/operations website loops, health-state badges and the See/Shape/Govern/Run thread map. Strengthen the atomic-layers field guide using the actual seven layers and actual component examples.

The accepted references are v4/posters/identity-playground.png, v4/motion/crazy-keyframes.png, and the selected extensions in LOOM_COMPLETE_PACKAGE.zip. This is approval of their direction, not a claim that every experimental mark was approved as the primary small-size logo. Existing navigation logo remains until a precise primary master is settled.

Implementation rules and reasons

• Rebuild artwork as vectors using the current Loom Site tokens. Raster concept sheets are references, not production masters. This retains the geometry while supporting responsive sizes and colour modes.
• Keep the clear product promise and the existing functional demonstrations. Identity motion is labelled as illustration; it never claims to execute an audit or repair.
• Each motion sequence has play/pause, previous/next, replay and directly selectable frames. Autoplay runs once on entering view, pauses offscreen and when the document is hidden, and is disabled for reduced motion. Transitions use the existing motion tokens. The four-second reading hold follows the selected boards and is recorded per sequence; it is distinct from the transition tokens.
• Operational state badges (Healthy, Attention, Broken, Action) are distinct from the existing score bands and their 90/75/60 thresholds. Preserve that distinction.
• Atomic composition means foundation, token, atom, molecule, organism, template and page. It is distinct from organisation/brand inheritance; dependencies may skip levels.
• Every new element is registered with its contract, examples, styles and both languages. Japanese remains an AI draft pending native review, consistent with the existing site.

Owner correction — 27 October

The owner rejected the experimental placement on the homepage and product pages. Those source files have been restored to Claude preview 99cf14b7. The new elements are drafts, retained only for review and in the system reference. Passing mechanism checks do not accept the artwork, page design or system adaptation. Establish the existing architecture, close reusable system gaps, then adapt the website through its page contracts.

Original experimental delivery boundary (not accepted)

Reusable capability: token-governed identity and explanatory motion composed by Loom Site on its own pages. Observable outcome: the site and the Library render the same six new elements, and readers can inspect all eight repair frames and actual atomic examples.

Requirement mapping: R04 (atomic composition) and R06 (reusable element authoring); current PRD SHP-09 (brand, illustration and localisation). Baseline: the owner-selected V4 package and the Claude preview source below. This is the website consumer delivery, not acceptance of the historical V2 builder journeys.

Dependencies: Claude's claude/site-visual at 99cf14b7, the existing registry/composer, semantic tokens, brand/content rules and accessible controls. This connected delivery applies the owner's visual decision. It does not establish 100% system consumption, a complete Figma library, a completed website rebuild, or a deployed release. Those remain explicit acceptance work.

Acceptance: site build, element and identity unit checks, browser keyboard/playback/reduced-motion/mobile/contrast checks; record observed results in docs/status.md. Review in this session is sequential self-review, not independent review.

System specification — 27 October continuation

This section is the implementation target for the owner's selected direction. It does not accept the earlier drafts or authorize website adaptation. Keep the existing homepage, page sequences, copy and product demonstrations at Claude preview 99cf14b7 until the reusable system passes its acceptance below.

Reusable capability: author, inspect and maintain an accessible identity family through the same Loom Site contracts, tokens, registry, Storybook and Library as every other element. Requirements: R02/R03/R04/R06/R07/R08/R09/R12; SHP-09/20/27 and PLT-09/10. Baseline coverage: S01–S03, F01–F14, T01–T04. Journey relevance: J1 inventory, J2 authoring, J4 composition, J5 consumption, J6 maintenance; AC2/AC3/AC5/AC7. These mappings do not accept the historical native-builder journeys.

Authority and preservation

1. Claude preview 99cf14b7 supplies the site architecture, copy, real demos and component implementations. Preserve them; improvements extend their system contracts.
2. The accepted visual references are the original logo package, retained outside this checkout. Store byte digests and relative source paths when producing vector masters. Never overwrite the originals.
3. Current Loom Base Selvedge tokens and D-SITE-014/018 supply colour/mode authority. Package cotton/ink/indigo are older values, remapped by role, not copied into component CSS. See is teal, Shape madder, Govern saffron and Run indigo in the later site. Older reversed See/Run comments must not determine new output.
4. A reference board, a vector master, an implemented component, an executed test and owner visual acceptance are separate facts. Draft stays draft while fidelity or required review is open. Preserve the current navigation mark; large expressive lettering does not establish the primary 16 px logo.
5. Basic illustration motion is within this owner-selected Site extension. It does not silently claim completion of the generic MVDS v2 motion/sound capability.

Shared contract and rendering requirements

Every family declares its source, anatomy, typed API, permitted variants, all applicable states, composition dependencies, component-token aliases, responsive rules, content constraints, accessibility, motion, examples, misuse examples, named checks and outstanding human/design-tool review. Missing checks remain unrun. A shared generic test reference is not a visual pass.

Three token tiers remain the requirement: Base primitives → semantic roles → element/part/state aliases. Contextual values such as field background are explicit inputs to component aliases. Existing Site direct-semantic consumption remains an adoption gap until migrated and tested; do not weaken MVDS to erase it. Preserve actual colour-mode behaviour when introducing aliases. Do not convert SVG coordinate geometry into spacing tokens: the artwork's internal grid is geometry, while CSS dimensions, padding, typography, borders and timings are governed design tokens.

Support light, dark and high contrast; forced colours preserves meaningful boundaries with system colours. Operational meaning always has shape and words. Decorative art is hidden from assistive technology; informative art has a concise equivalent description. Controls have visible focus, at least the existing 44 px target, predictable DOM order, no focus movement during playback and no autoplay announcements. English and Japanese labels use the existing localisation status; Japanese remains unreviewed until native review. Text expansion grows the component without clipping or overlapping.

Selected family definitions

Playback and state model

The shared player owns playback only; each sequence owns its frames and labels. A frame is a stable ID, meaning and authored SVG scene. Initial markup renders the final scene and description. JavaScript reveals controls only after successful mount. Manual selection pauses, updates one current-frame indicator and one polite announcement; background autoplay is silent. Leaving view, hiding the document or enabling reduced motion pauses immediately. Reduced-motion replay selects the first still; subsequent stepping remains manual. A deliberate Play may advance stills, with no spatial transition. Remount cleans observers, listeners and timers before creating new ones. Invalid sequence/frame values are rejected; missing enhancement retains the complete static explanation.

Reference timings come from the boards: repair at 0/4/8/12/16/20/24/28 seconds and assembly at 0/4/8/12/16/20 seconds. Timings are sequence data; transition easing/duration use existing motion roles. A changed timing must be explicit in the contract, never an unexplained hard-coded interval.

Acceptance before website adaptation

• Baseline report matches a fresh scan of the final output; page usage is correct on Windows and POSIX; source fingerprints change for implementation/token/style changes even without version bumps. Historical failures are retained.
• Token aliases resolve for all supported modes; every new element's styles consume its defined component aliases. Existing system adoption gaps remain itemised until repaired. No copied raw palette values or invented branding.
• Every selected family above has its own source mapping, usable implementation, complete state definitions, real examples and meaningful misuse handling. Registry, Library, Storybook and exported contracts agree on the same source identity.
• Browser checks exercise all frames/variants, keyboard operation, reduced motion, no JavaScript, pause on hidden/offscreen, mobile/desktop, light/dark/high-contrast/forced-colour modes and text expansion. Geometry is reviewed against the original boards side by side. Screenshots are evidence, not automatically approved baselines.
• Full system requirements remain visible: foundations, token/mode export, Base/Site relationships, component states, templates/page declarations, content/localisation, accessibility, governance, design-tool correspondence and maintenance. Passing V4 tests alone cannot make the system ready.
• Website adaptation remains closed while blocking system requirements are unresolved. Once ready, work follows existing page declarations and the owner's structural order, preserving clear copy and real product proof.

Review method: sequential self-review using system readiness, system quality and product conformance methods; no independent reviewer or human visual acceptance is implied.

28 October owner refinement directive

The owner explicitly authorizes upgrading the selected concepts into finished system assets and a revised logo. This supersedes the earlier instruction to preserve the previous navigation mark until a precise master exists. Apply the reviewed, verified refined system logo through the existing 26 px currentColor API; preserve website placement, architecture and copy. Selection of the direction is accepted; refined geometry remains a review candidate, not owner-approved final artwork. Original source references and external rights status are unchanged.

Authored geometry is shared by runtime renderers and transparent SVG exports. Light, dark and high-contrast paint resolves from Loom Base tokens; mono/reverse use the existing ink/cotton roles. Complex expressive lettering remains separate from the outlined Archivo primary wordmark and optical favicon cut. Assembly and other narrative motion use the existing motion profile with real interpolated transitions, reduced-motion final states and explicit controls.

EX-SITE-001: Interactive captions keep their own classes

Exception

The interactives keep their ix-*-caption classes until they move into the Showcase frame's caption (D-SITE-007).

Why it is allowed for now

The move is on the Loom Site work list; until then the exception says plainly what is not done.

EX-SITE-002: The proof section borrows the lead section's head

Exception

proof-section uses l-lead-head and l-lead-copy until the section head is one molecule.

Why it is allowed for now

The move is on the Loom Site work list; until then the exception says plainly what is not done.

EX-SITE-003: Older showcases write their own frame

Exception

Score us, the mini audit and the ix-* interactives write the frame markup themselves instead of calling the Showcase frame module (D-SITE-008).

Why it is allowed for now

The move is on the Loom Site work list; until then the exception says plainly what is not done.

EX-SITE-004: Stand-alone apps are outside the page builder

Exception

The health check, survey, contact form and product tour are static pages; their markup is not yet composed from registered templates. check-pages lists them as exceptions.

Why it is allowed for now

The move is on the Loom Site work list; until then the exception says plainly what is not done.

Closed

The task pages are now generated from registered elements (the Task page and Task body templates, the task header and footer, and each app's organism) by scripts/site/apps.ts. check_composition checks them like every other page.

EX-SITE-005: The contact form's fallback link names a person

Exception

The site names no people (owner, 26 Oct 2026). The contact form's fallback ("if the form does not work for you") links to the founder's portfolio site, whose domain is a name. It is the only other way in that the site offers, so it stays until the owner names another channel (a shared inbox or a company page). The name guard (scripts/site/system/guard-names.ts) excuses only this link, only on /contact/ and /ja/contact/.

Why it is allowed for now

Removing it would leave a visitor whose form fails with no way to reach Loom. The decision belongs to the owner.

Closed

The owner decided that contact goes through the form only. The fallback line and its link are removed from the contact form (EN and JA), its failure message now says to try again with the text kept in the form, and the name guard no longer excuses anything.