# devabas/design-system architecture

> Architecture diagram of the GitHub repository devabas/design-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devabas/design-system
- Repository: https://github.com/devabas/design-system

## Overview

Agent-Ready Design System is a Claude Code plugin for setting up, auditing, and maintaining a project’s token-based design system, plus installing enforcement gates. The main workflow is a user choosing a command: setup provides a starter token architecture; audit inventories and checks the project, then produces a report; fix addresses selected findings, re-audits, and compares results; harness installs checks and hooks. The graph includes documented command capabilities and sampled script dependencies; internal wiring for unsampled skill instructions is not inferred.

Main entry points: [`plugins/design-system/scripts/check-tokens.mjs`](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/check-tokens.mjs) (Token checks), [`plugins/design-system/skills/audit/SKILL.md`](https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/audit/SKILL.md) (Audit command), [`plugins/design-system/skills/harness/SKILL.md`](https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/harness/SKILL.md) (Harness command), [`plugins/design-system/assets/harness/core/run-gates.mjs`](https://github.com/devabas/design-system/blob/main/plugins/design-system/assets/harness/core/run-gates.mjs) (Gate runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Agent workflows"]
  node_setup["Setup command<br/>[SKILL.md]"]
  node_starter["Starter architecture"]
  node_audit_skill["Audit command<br/>[SKILL.md]"]
  node_fix["Fix command<br/>[SKILL.md]"]
  node_harness_skill["Harness command<br/>[SKILL.md]"]
end

subgraph group_audit["Audit and reports"]
  node_scan["Project inventory<br/>[scan.mjs]"]
  node_report_render["Report rendering<br/>[render-report.mjs]"]
  node_report_compare["Report comparison"]
end

subgraph group_tokens["Token validation"]
  node_token_check["Token checks<br/>[check-tokens.mjs]"]
  node_rules_check["Rules contract"]
  node_dtcg["DTCG resolver<br/>[dtcg.mjs]"]
  node_color["Color calculations<br/>[color.mjs]"]
  node_settings["Project settings"]
  node_token_files["Project token files"]
end

subgraph group_enforcement["Enforcement gates"]
  node_gates["Gate runner<br/>[run-gates.mjs]"]
  node_gate_config["Gate configuration<br/>[design-system.yml]"]
  node_hooks["Claude Code hooks"]
  node_search_scope["Search boundary hook<br/>[search-scope.mjs]"]
  node_generated_check["Generated output check"]
end

node_user(("Project maintainer"))
node_project["Web project"]

node_user -->|"chooses setup"| node_setup
node_user -->|"requests audit"| node_audit_skill
node_user -->|"requests fixes"| node_fix
node_user -->|"requests gates"| node_harness_skill
node_setup -->|"provides starter"| node_starter
node_audit_skill -->|"inventories project"| node_scan
node_scan -->|"reads files"| node_project
node_audit_skill -->|"checks tokens"| node_token_check
node_audit_skill -->|"checks rules"| node_rules_check
node_audit_skill -->|"writes report"| node_report_render
node_fix -->|"compares audits"| node_report_compare
node_report_compare -->|"validates reports"| node_report_render
node_rules_check -->|"reads token model"| node_token_check
node_token_check -->|"loads and resolves"| node_dtcg
node_token_check -->|"checks derived colors"| node_color
node_token_check -->|"loads settings"| node_settings
node_rules_check -->|"loads settings"| node_settings
node_dtcg -->|"reads token sources"| node_token_files
node_harness_skill -->|"installs gates"| node_gates
node_harness_skill -->|"installs hooks"| node_hooks
node_harness_skill -->|"configures checks"| node_gate_config
node_gates -->|"runs check"| node_token_check
node_gates -->|"runs check"| node_rules_check
node_gates -.->|"runs profile check"| node_generated_check
node_hooks -->|"dispatches search guard"| node_search_scope
node_search_scope -->|"constrains searches"| node_project
node_generated_check -->|"reads output settings"| node_settings
node_generated_check -->|"checks generated files"| node_project

click node_setup "https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/setup/SKILL.md"
click node_starter "https://github.com/devabas/design-system/tree/main/plugins/design-system/assets/setup"
click node_audit_skill "https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/audit/SKILL.md"
click node_fix "https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/fix/SKILL.md"
click node_harness_skill "https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/harness/SKILL.md"
click node_scan "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/scan.mjs"
click node_report_render "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/render-report.mjs"
click node_report_compare "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/compare-reports.mjs"
click node_token_check "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/check-tokens.mjs"
click node_rules_check "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/check-rules-contract.mjs"
click node_dtcg "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/lib/dtcg.mjs"
click node_color "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/lib/color.mjs"
click node_settings "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/lib/project-modules.mjs"
click node_token_files "https://github.com/devabas/design-system/tree/main/plugins/design-system/assets/setup/design-system/tokens"
click node_gates "https://github.com/devabas/design-system/blob/main/plugins/design-system/assets/harness/core/run-gates.mjs"
click node_gate_config "https://github.com/devabas/design-system/blob/main/plugins/design-system/assets/harness/core/design-system.yml"
click node_hooks "https://github.com/devabas/design-system/tree/main/plugins/design-system/assets/harness/adapters/claude-code"
click node_search_scope "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/search-scope.mjs"
click node_generated_check "https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/profiles/terrazzo-tailwind-v4/check-generated.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup,node_starter,node_audit_skill,node_fix,node_harness_skill toneBlue
class node_scan,node_report_render,node_report_compare toneAmber
class node_token_check,node_rules_check,node_dtcg,node_color,node_settings,node_token_files toneMint
class node_gates,node_gate_config,node_hooks,node_search_scope,node_generated_check toneRose
class node_user,node_project toneIndigo
```

## Components

### Agent workflows

- [Setup command](https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/setup/SKILL.md): `plugins/design-system/skills/setup/SKILL.md`
- [Starter architecture](https://github.com/devabas/design-system/tree/main/plugins/design-system/assets/setup): `plugins/design-system/assets/setup`
- [Audit command](https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/audit/SKILL.md): `plugins/design-system/skills/audit/SKILL.md`
- [Fix command](https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/fix/SKILL.md): `plugins/design-system/skills/fix/SKILL.md`
- [Harness command](https://github.com/devabas/design-system/blob/main/plugins/design-system/skills/harness/SKILL.md): `plugins/design-system/skills/harness/SKILL.md`

### Audit and reports

- [Project inventory](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/scan.mjs): `plugins/design-system/scripts/scan.mjs`
- [Report rendering](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/render-report.mjs): `plugins/design-system/scripts/render-report.mjs`
- [Report comparison](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/compare-reports.mjs): `plugins/design-system/scripts/compare-reports.mjs`

### Token validation

- [Token checks](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/check-tokens.mjs): `plugins/design-system/scripts/check-tokens.mjs`
- [Rules contract](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/check-rules-contract.mjs): `plugins/design-system/scripts/check-rules-contract.mjs`
- [DTCG resolver](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/lib/dtcg.mjs): `plugins/design-system/scripts/lib/dtcg.mjs`
- [Color calculations](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/lib/color.mjs): `plugins/design-system/scripts/lib/color.mjs`
- [Project settings](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/lib/project-modules.mjs): `plugins/design-system/scripts/lib/project-modules.mjs`
- [Project token files](https://github.com/devabas/design-system/tree/main/plugins/design-system/assets/setup/design-system/tokens): `plugins/design-system/assets/setup/design-system/tokens`

### Enforcement gates

- [Gate runner](https://github.com/devabas/design-system/blob/main/plugins/design-system/assets/harness/core/run-gates.mjs): `plugins/design-system/assets/harness/core/run-gates.mjs`
- [Gate configuration](https://github.com/devabas/design-system/blob/main/plugins/design-system/assets/harness/core/design-system.yml): `plugins/design-system/assets/harness/core/design-system.yml`
- [Claude Code hooks](https://github.com/devabas/design-system/tree/main/plugins/design-system/assets/harness/adapters/claude-code): `plugins/design-system/assets/harness/adapters/claude-code`
- [Search boundary hook](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/search-scope.mjs): `plugins/design-system/scripts/search-scope.mjs`
- [Generated output check](https://github.com/devabas/design-system/blob/main/plugins/design-system/scripts/profiles/terrazzo-tailwind-v4/check-generated.mjs): `plugins/design-system/scripts/profiles/terrazzo-tailwind-v4/check-generated.mjs`

### Other components

- **Project maintainer**
- **Web project**

## Connections

- Project maintainer → Setup command: chooses setup
- Project maintainer → Audit command: requests audit
- Project maintainer → Fix command: requests fixes
- Project maintainer → Harness command: requests gates
- Setup command → Starter architecture: provides starter
- Audit command → Project inventory: inventories project
- Project inventory → Web project: reads files
- Audit command → Token checks: checks tokens
- Audit command → Rules contract: checks rules
- Audit command → Report rendering: writes report
- Fix command → Report comparison: compares audits
- Report comparison → Report rendering: validates reports
- Rules contract → Token checks: reads token model
- Token checks → DTCG resolver: loads and resolves
- Token checks → Color calculations: checks derived colors
- Token checks → Project settings: loads settings
- Rules contract → Project settings: loads settings
- DTCG resolver → Project token files: reads token sources
- Harness command → Gate runner: installs gates
- Harness command → Claude Code hooks: installs hooks
- Harness command → Gate configuration: configures checks
- Gate runner → Token checks: runs check
- Gate runner → Rules contract: runs check
- Gate runner → Generated output check: runs profile check
- Claude Code hooks → Search boundary hook: dispatches search guard
- Search boundary hook → Web project: constrains searches
- Generated output check → Project settings: reads output settings
- Generated output check → Web project: checks generated files