What arrives in your repository

Files changed

• .claude/skills/acme-app-design-system/SKILL.md+46

  The same guidance as a skill for Claude Code and similar agents. Owned by: the system owner

  ---
  name: acme-app-design-system
  description: "Build and review UI with the Acme App design system (acme-app): components with lifecycle status, token…
  ---
  
  # Acme App design system
  
  > Generated by Loom from the system's records; do not edit by hand. Regenerate with `npx loom agent-pack`.
  
  ## When to use
  
  - Writing or changing UI in a repository that uses `acme-app`.
  - Choosing a colour, spacing, radius, type or motion value: use a token.
  - Reviewing UI for drift from the system (off-system components, raw values, style overrides, accessibility).
  
  ## Workflow
  
  1. Find what exists: the component index below, then `references/components.md` for the full contract (import, props …
  2. Choose by lifecycle status: stable first; a beta item if no stable one fits, named as beta in your answer and in a…
  3. Take every value from `references/tokens.md`. No raw hex, rgb or px values.
  4. Check the rules and patterns in `references/governance.md` before finishing.
  5. If something is missing, say so and propose it; do not build an off-system copy.
  6. With the Loom MCP server configured, `check_composition` and `audit_code` validate the result.
  
  ## Component index
  
  | Component | Import | Status | Purpose |
  | --- | --- | --- | --- |
  | Badge | `import { Badge } from "acme-app";` | draft (declared "proposal") | Badge: purpose not recorded yet (conver…
  | Button | `import { Button } from "acme-app";` | draft (declared "proposal") | The main action on a screen. |
  | Card | `import { Card } from "acme-app";` | draft (declared "proposal") | Card: purpose not recorded yet (converted…
  
  ## Tokens at a glance
  
  - **color:** 16 tokens
  - **spacing:** 7 tokens
  
  Every token, with value, role and restrictions: `references/tokens.md`.
  
  ## References

  6 more lines in the file.

• AGENTS.md+54

  What coding agents read before they write interface in this repository. Owned by: the system owner

  # AGENTS.md: Acme App design system
  
  > Generated by Loom from the system's records; do not edit by hand. Regenerate with `npx loom agent-pack`.
  > Records: knowledge digest `09ac1ecf2ca2`, 23 tokens, 3 components, 0 patterns.
  
  ## Use the design system
  
  - **Package:** `acme-app` 0.0.0. Import components from it; never copy their source.
  - **Skill:** `.claude/skills/acme-app-design-system/SKILL.md` (Agent Skills format) holds the workflow; its `referenc…
  - **Loom MCP server (optional):** when it is configured for this repository, prefer its tools for exact, current answ…
  - **Loom CLI:** `npx loom info --json` (project setup), `npx loom doc <Component>`, `npx loom token <name>`, and `npx…
  
  ## Rules for agents
  
  1. Build UI from the system's components. Use the exact import line and only documented props and values.
  2. Use tokens for colour, spacing, radius, type, elevation and motion. Never write raw hex, rgb or px values.
  3. Lifecycle: Every component and pattern carries a lifecycle status: draft → beta → stable → deprecated. Prefer stab…
  4. Customise through slots, variants and overridable tokens; do not override a component's className or style.
  5. Accessibility obligations of every component you use are requirements, not suggestions; accessibility findings alw…
  6. When you open a pull request, list every beta component it uses as beta in the pull request body.
  7. If the system lacks what you need, do not build it off-system: say so, use the closest fit only if it truly fits, …
  
  ## Lifecycle status
  
  | Status | Meaning | Components and patterns | Agents |
  | --- | --- | --- | --- |
  | draft | Work in progress or a proposal. Not for production UI; it may change or disappear without notice. | 3 | Not…
  | beta | Usable in product UI. The API may still change in a minor release; changes are announced in the changelog. |…
  | stable | Changes follow semver. A breaking change needs a major release with a codemod or migration pull request. |…
  | deprecated | Being removed. Existing uses keep working until the removal version; new UI must not use it. | 0 | Not…
  
  Every item has a recorded status. Definitions of done: `references/governance.md` in the skill.
  
  ## Components by status
  
  - **Draft (not suggested; not for production):** Badge, Button, Card
  
  ## Accepted rules
  
  - **Use colour tokens, not raw colours** (`loom.raw-colour`, warn): Raw colours bypass themes, modes and contrast che…

  14 more lines in the file.

• DESIGN.md+275

  The whole system in one Markdown file, generated from the records. Owned by: the system owner

  ---
  version: alpha
  name: "Acme App"
  description: "The Acme App design system (acme-app), exported by Loom from its records: 23 tokens, 3 components, 0 pa…
  colors:
    "--semantic-surface-default": "#ffffff"
    "--semantic-text-default": "#ffffff"
    "--semantic-border-default": "#e5e7eb"
    "--semantic-action-primary": "#2563eb"
  spacing:
    "--proto-space-2": "8px"
    "--proto-space-4": "16px"
    "--space-1": "4px"
    "--space-2": "6px"
    "--space-3": "8px"
    "--space-4": "16px"
    "--space-5": "24px"
  ---
  
  # Acme App
  
  > Generated by Loom from the system's records; do not edit by hand. Regenerate with `npx loom design-md --out DESIGN.…
  > Records: knowledge digest `09ac1ecf2ca2`, source `6682be71c9f7`, observed 2026-10-25T21:55:02.612Z. 23 tokens, 3 co…
  > Format: DESIGN.md alpha (github.com/google-labs-code/design.md). Token names are the system's own. Values are the d…
  
  ## Overview
  
  Acme App ships as `acme-app` 0.0.0. Owner: Design system owner. Rights: Client-owned source; not for redistribution.
  
  - **principles** guidance: not defined (no principles foundation in the records).
  
  Known limitations:
  
  - Generic project: tokens, contracts and snapshot only; no verified reusable runtime. (no-runtime)
  
  ### Token tiers and modes
  
  Tiers are stated for 18 of 23 tokens, inferred by Loom for the rest (inferred).
  
  | Tier | Tokens |

  235 more lines in the file.

• loom.config.json+26

  Tells the loom command where your system's records live. Owned by: your engineers

  {
    "schema": "loom.config/1",
    "system": {
      "id": "acme-app",
      "name": "Acme App"
    },
    "builder": "loom/system/acme-app.builder.json",
    "tokens": "loom/system/tokens.dtcg.json",
    "contracts": "loom/system/contracts.json",
    "components": {
      "package": "acme-app",
      "source": "src/components"
    },
    "app": [
      "src"
    ],
    "governance": "loom",
    "stack": {
      "framework": "react",
      "bundler": "vite",
      "styling": [],
      "typescript": true,
      "packageManager": "npm"
    }
  }
  

• loom/conversion/report.md+391

  The first audit: scores, findings and their evidence. Owned by: the system owner

  # acme-app: 9/100, Loose threads
  
  <!-- loom:agent-generated {"schema":"loom.provenance/1.0.0","generator":"loom-conversion","generatorVersion":"1.0.0",…
  > **Machine-generated by loom-conversion (no AI model involved)** on 2026-10-25. Not yet reviewed by a human. Label: …
  
  **Loom conversion report** — how this app is *structured, governed and used*, and the AI-ready system Loom generated …
  
  | | |
  |---|---|
  | Input | `src` (app with no design system) |
  | Version | 1.0.0 |
  | Consumer code scanned | `src` — 5 files |
  | Findings | 1 critical · 27 high · 9 medium · 3 low · 1 info |
  | Generated | 2026-10-25 |
  
  ## Headline
  
  - acme-app 1.0.0: 9/100 for structure, governance and use: Loose threads.
  - 0 of 4 components have a usage contract
  - 5 proto-tokens live in CSS custom properties with no types, roles or descriptions
  - 3 of 3 semantic/component tokens hold literals instead of aliasing a lower tier
  - Required modes missing: light, dark, high contrast
  - No DTCG token file: tokens cannot be validated, exchanged or compiled by standard tools
  
  ## Scorecard
  
  | Area | Score | | Biggest issue |
  |---|---:|---|---|
  | Foundations and tokens | 38 | ████░░░░░░ | 5 proto-tokens live in CSS custom properties with no types, roles or des…
  | Components | 4 | ░░░░░░░░░░ | 0 of 4 components have a usage contract |
  | Patterns and pages | – | not assessed | No pattern or template records in the inputs |
  | Usage | 13 | █░░░░░░░░░ | 3 components in use, none with a contract |
  | Governance | 3 | ░░░░░░░░░░ | Owners per component: absent |
  | Brand, illustration, microcopy and localisation | 0 | ░░░░░░░░░░ | Brand rules: absent |
  | Tools and sync | 0 | ░░░░░░░░░░ | 4 of 4 components have no story |
  | AI readiness | 0 | ░░░░░░░░░░ | No machine-readable component contracts |
  | **Overall** | **9** | █░░░░░░░░░ | |
  
  ## Before → after
  

  351 more lines in the file.

• loom/governance.json+94

  Who owns each area, who covers for them, and the service level for decisions. Owned by: the system owner

  {
    "$comment": "Seeded by Loom for a tiny team (1 person). Every value is a proposal: edit it to how you actually work…
    "schema": "loom.governance/1.0.0",
    "provenance": "real",
    "systemOwner": "Design system owner",
    "guild": [
      {
        "name": "Design system owner",
        "discipline": "design"
      },
      {
        "name": "Design system owner",
        "discipline": "engineering"
      },
      {
        "name": "Design system owner",
        "discipline": "accessibility"
      }
    ],
    "areas": [
      {
        "id": "foundations",
        "label": "Foundations (tokens, type, modes)",
        "owner": "Design system owner",
        "scope": {
          "tiers": [
            "foundation"
          ],
          "ruleCategories": [
            "colour",
            "spacing"
          ]
        },
        "autonomy": "suggest"
      },
      {
        "id": "components",
        "label": "Components",
        "owner": "Design system owner",
        "scope": {

  54 more lines in the file.

• loom/rituals.json+36

  The weekly triage and other rituals; Loom drafts their agendas from the records. Owned by: the system owner

  [
    {
      "owner": "Design system owner",
      "id": "pr-review",
      "name": "Review a Loom pull request",
      "cadence": "on-demand",
      "minutes": 15,
      "attendees": [
        "system-owner",
        "area-owner"
      ],
      "purpose": "When Loom opens a pull request, the owner of that area reviews it within the service level. No standi…
      "agenda": [
        "overdue-reviews",
        "released-changes"
      ]
    },
    {
      "owner": "Design system owner",
      "id": "quarterly-tidy",
      "name": "Quarterly tidy",
      "cadence": "quarterly",
      "minutes": 30,
      "attendees": [
        "guild"
      ],
      "purpose": "Read the health numbers, close or renew exceptions, decide the next migration step.",
      "agenda": [
        "health-metrics",
        "expiring-exceptions",
        "expired-exceptions",
        "deprecations-due"
      ]
    }
  ]
  

• loom/rules.json+66

  The rules the checks enforce, each with an owner and a reason. Owned by: the area owners

  [
    {
      "id": "acme-app.modes-from-tokens",
      "version": "0.1.0",
      "title": "Colour modes come from tokens, not per-selector overrides",
      "owner": "Design system owner",
      "rationale": "The starter maps light and dark to token modes; a new rule that restyles a selector for dark mode b…
      "severity": "warn",
      "category": "colour",
      "check": {
        "kind": "manual",
        "how": "Review new CSS in a pull request: no new rules scoped to the dark selector; set the semantic token's da…
      },
      "status": "proposed",
      "history": [
        {
          "version": "0.1.0",
          "date": "2026-10-25",
          "change": "Proposed by the Loom greenfield starter."
        }
      ]
    },
    {
      "id": "acme-app.keeps-the-look",
      "version": "0.1.0",
      "title": "Each migration step keeps every key screen within 0.5% pixel difference",
      "owner": "Design system owner",
      "rationale": "Migration to the system must not change the look (owner rule); look:diff measures it.",
      "severity": "warn",
      "category": "migration",
      "check": {
        "kind": "manual",
        "how": "Run npm run look:diff on the key screens in every colour mode before merging a migration step."
      },
      "status": "proposed",
      "history": [
        {
          "version": "0.1.0",
          "date": "2026-10-25",
          "change": "Proposed by the Loom greenfield starter."

  26 more lines in the file.

• loom/system/contracts.json+292

  One contract per component: what it is for, when not to use it, its states and accessibility. Owned by: each component's owner

  {
    "schemaVersion": "2.1.0",
    "snapshotDigest": "2c76c2b16e0a7c3d6eeb5e0bcd7bd6b6f075977a5dc3165ddf39662522165a2c",
    "contracts": [
      {
        "schemaVersion": "2.1.0",
        "behavior": {
          "schemaVersion": "1.0.0",
          "domains": {
            "transitions": {
              "applicability": "needs-review",
              "rationale": "Applicability and structured obligations require assessment against source and consumers.",
              "rules": []
            },
            "focus": {
              "applicability": "needs-review",
              "rationale": "Applicability and structured obligations require assessment against source and consumers.",
              "rules": []
            },
            "announcements": {
              "applicability": "needs-review",
              "rationale": "Applicability and structured obligations require assessment against source and consumers.",
              "rules": []
            },
            "controlledState": {
              "applicability": "needs-review",
              "rationale": "Applicability and structured obligations require assessment against source and consumers.",
              "rules": []
            },
            "content": {
              "applicability": "needs-review",
              "rationale": "Applicability and structured obligations require assessment against source and consumers.",
              "rules": []
            },
            "responsive": {
              "applicability": "needs-review",
              "rationale": "Applicability and structured obligations require assessment against source and consumers.",
              "rules": []
            },
            "localization": {

  252 more lines in the file.

• loom/system/tokens.dtcg.json+409

  Your tokens in the open DTCG format, sorted into tiers. Owned by: the Foundations owner

  {
    "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
    "$description": "acme-app: first typed token set, generated by Loom from an app with no design system. Proto-tokens…
    "$extensions": {
      "app.loom": {
        "generatedAt": "2026-10-25T21:55:02.562Z",
        "exporterFindings": [],
        "modes": {
          "detected": [
            "default"
          ],
          "decision": [],
          "status": "needs-human-decision"
        },
        "validation": {
          "format": "DTCG 2025.10",
          "leaves": 23,
          "valid": 23,
          "invalid": [],
          "unresolvedAliases": []
        }
      },
      "app.loom.provenance": {
        "schema": "loom.provenance/1.0.0",
        "generator": "loom-conversion",
        "generatorVersion": "1.0.0",
        "model": null,
        "provider": null,
        "generatedAt": "2026-10-25T21:55:02.594Z",
        "ai_generated": false,
        "human_reviewed": false,
        "label": "loom:agent-generated",
        "method": "Deterministic static analysis of the repository (no AI model); every field is marked generated-from-…
      }
    },
    "proto": {
      "color-primary": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",

  369 more lines in the file.