# zanwei/design-dna architecture

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

- Interactive diagram: https://gitdiagram.com/zanwei/design-dna
- Repository: https://github.com/zanwei/design-dna

## Overview

1. **Repository role**
   - This is not a runtime application; it is an **Agent Skill package**.
   - Its job is to teach a host agent how to **extract, structure, and apply visual design identity** as a reusable artifact called **Design DNA**.

2. **Primary execution boundary**
   - The real “engine” is external: the **agent platform** that loads this skill via the **Agent Skills spec**.
   - The repo itself contains the instructions, schema, and guidance files that the host agent reads and executes.

3. **Core artifact: Design DNA JSON**
   - The key data object in the architecture is a **machine-readable JSON profile**.
   - This profile captures three dimensions:
     - **Design tokens**: measurable system values like color, type, spacing, layout, motion, etc.
     - **Design style**: qualitative traits like mood, composition, brand voice, and interaction feel.
     - **Visual effects**: richer rendering behaviors like canvas, WebGL, shaders, glassmorphism, and scroll motion.
   - The JSON is intended to be versioned, reused, and passed from analysis to generation.

4. **Three-phase workflow**
   - The skill is organized around a clear pipeline:
     - **Structure**: expose the full schema and field meanings.
     - **Analyze**: derive a complete Design DNA profile from screenshots, images, or URLs.
     - **Generate**: use the DNA JSON plus new content to produce an implementation, typically self-contained HTML/CSS/JS.
   - This pipeline is the main architectural flow for any diagram.

5. **`SKILL.md` as the operational contract**
   - `SKILL.md` is the central instruction file that the agent actually follows.
   - It defines the skill behavior, the workflow, and the expectations for analysis and generation.
   - In architecture terms, this is the **control layer**.

6. **`references/schema.md` as the data model**
   - This file defines the **shape of the Design DNA**.
   - It is the schema boundary between visual input and structured output.
   - Any diagram should show it as the **specification layer** that constrains what the analyzer must extract.

7. **`references/generation-guide.md` as the implementation policy**
   - This file governs how the agent should transform DNA JSON into a working design implementation.
   - It sits on the output side of the pipeline and acts as the **rendering/generation boundary**.
   - It is especially important because it likely standardizes how the final UI is composed from the extracted DNA.

8. **Localized README files as presentation-only mirrors**
   - The multiple `README.*.md` files are translated versions of the same top-level usage and concept documentation.
   - They do not change behavior; they expand accessibility for different languages.
   - In a diagram, these are documentation surfaces, not runtime subsystems.

9. **`docs/` and `references/` as support content**
   - `references/` contains the authoritative technical guidance for the skill’s schema and generation behavior.
   - `docs/` appears to be supplemental documentation space.
   - Both are part of the **knowledge base** the agent uses, rather than executable logic.

10. **Installation and distribution flow**
   - The repo is designed to be installed with the `skills` CLI via `npx`.
   - That means the distribution boundary is GitHub repository → `skills` installer → host agent environment.
   - This matters architecturally because the skill is consumed as a packaged instruction set, not imported as source code.

11. **External inputs and outputs**
   - **Inputs**: screenshots, images, live URLs, and user content.
   - **Intermediate output**: a complete Design DNA JSON profile.
   - **Final output**: a faithful design implementation, usually a self-contained UI artifact.
   - The major architectural handoff is from **visual references** to **structured DNA**, then from **structured DNA** to **generated design**.

12. **What to draw in an architecture diagram**
   - Show three main boxes:
     - **Reference inputs**: images / screenshots / URLs
     - **Skill instructions and schema**: `SKILL.md`, `references/schema.md`, `references/generation-guide.md`
     - **Generated output**: Design DNA JSON and then implementation
   - Indicate that the **agent runtime** sits outside the repo and performs the work by following the skill content.

Main entry points: [`README.md`](https://github.com/zanwei/design-dna/blob/main/README.md) (README), [`SKILL.md`](https://github.com/zanwei/design-dna/blob/main/SKILL.md) (SKILL.md), [`references/generation-guide.md`](https://github.com/zanwei/design-dna/blob/main/references/generation-guide.md) (Gen guide), [`references`](https://github.com/zanwei/design-dna/tree/main/references) (References)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External runtime"]
  node_agent_platform(("Agent platform<br/>runtime"))
  node_skills_installer["Skills CLI<br/>installer"]
  node_visual_inputs["Visual inputs<br/>input set"]
end

subgraph group_repo["Repository"]
  node_skill_md["SKILL.md<br/>control spec<br/>[SKILL.md]"]
  node_schema_md["Schema<br/>data model<br/>[schema.md]"]
  node_gen_guide["Gen guide<br/>policy guide"]
  node_readme_en["README<br/>overview doc<br/>[README.md]"]
  node_readme_es["README es<br/>localized doc<br/>[README.es.md]"]
  node_readme_ja["README ja<br/>localized doc<br/>[README.ja.md]"]
  node_readme_ko["README ko<br/>localized doc<br/>[README.ko.md]"]
  node_readme_zhcn["README zh-CN<br/>localized doc<br/>[README.zh-CN.md]"]
  node_readme_zhtw["README zh-TW<br/>localized doc<br/>[README.zh-TW.md]"]
  node_docs["Docs"]
  node_references["References<br/>knowledge base"]
  node_repo_package{{"Skill package<br/>distribution"}}
end

node_design_dna[("Design DNA<br/>json profile")]
node_generated_impl["Implementation<br/>ui artifact"]

node_skills_installer -->|"installs"| node_agent_platform
node_repo_package -->|"distributed via"| node_skills_installer
node_agent_platform -->|"loads"| node_skill_md
node_skill_md -->|"binds"| node_schema_md
node_skill_md -->|"drives"| node_gen_guide
node_visual_inputs -->|"provided to"| node_agent_platform
node_agent_platform -->|"extracts"| node_design_dna
node_schema_md -->|"constrains"| node_design_dna
node_design_dna -->|"feeds"| node_gen_guide
node_gen_guide -->|"renders"| node_generated_impl
node_readme_en -.->|"introduces"| node_skill_md
node_readme_es -.->|"mirrors"| node_readme_en
node_readme_ja -.->|"mirrors"| node_readme_en
node_readme_ko -.->|"mirrors"| node_readme_en
node_readme_zhcn -.->|"mirrors"| node_readme_en
node_readme_zhtw -.->|"mirrors"| node_readme_en
node_docs -.->|"supports"| node_references
node_references -->|"contains"| node_schema_md
node_references -->|"contains"| node_gen_guide

click node_skill_md "https://github.com/zanwei/design-dna/blob/main/SKILL.md"
click node_schema_md "https://github.com/zanwei/design-dna/blob/main/references/schema.md"
click node_gen_guide "https://github.com/zanwei/design-dna/blob/main/references/generation-guide.md"
click node_readme_en "https://github.com/zanwei/design-dna/blob/main/README.md"
click node_readme_es "https://github.com/zanwei/design-dna/blob/main/README.es.md"
click node_readme_ja "https://github.com/zanwei/design-dna/blob/main/README.ja.md"
click node_readme_ko "https://github.com/zanwei/design-dna/blob/main/README.ko.md"
click node_readme_zhcn "https://github.com/zanwei/design-dna/blob/main/README.zh-CN.md"
click node_readme_zhtw "https://github.com/zanwei/design-dna/blob/main/README.zh-TW.md"
click node_docs "https://github.com/zanwei/design-dna/tree/main/docs"
click node_references "https://github.com/zanwei/design-dna/tree/main/references"

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_agent_platform,node_skills_installer,node_visual_inputs toneBlue
class node_skill_md,node_schema_md,node_gen_guide,node_readme_en,node_readme_es,node_readme_ja,node_readme_ko,node_readme_zhcn,node_readme_zhtw,node_docs,node_references,node_repo_package toneAmber
class node_design_dna,node_generated_impl toneNeutral
```

## Components

### External runtime

Host-side agent platform, installer, and visual inputs that consume the skill.

- **Agent platform**: runtime · External agent environment that loads and executes the skill instructions.
- **Skills CLI**: installer · npx-based installer/distribution boundary for packaging the skill into the host environment.
- **Visual inputs**: input set · Screenshots, images, live URLs, and user-provided content used as design reference.

### Repository

Skill package content that defines the design-dna workflow and guidance.

- [SKILL.md](https://github.com/zanwei/design-dna/blob/main/SKILL.md): control spec · Operational contract that tells the host agent how to run the skill. · `SKILL.md`
- [Schema](https://github.com/zanwei/design-dna/blob/main/references/schema.md): data model · Authoritative definition of the Design DNA JSON structure and required fields. · `references/schema.md`
- [Gen guide](https://github.com/zanwei/design-dna/blob/main/references/generation-guide.md): policy guide · Rules for turning Design DNA JSON into a working design implementation. · `references/generation-guide.md`
- [README](https://github.com/zanwei/design-dna/blob/main/README.md): overview doc · Primary usage and concept documentation. · `README.md`
- [README es](https://github.com/zanwei/design-dna/blob/main/README.es.md): localized doc · Spanish presentation copy of the top-level documentation. · `README.es.md`
- [README ja](https://github.com/zanwei/design-dna/blob/main/README.ja.md): localized doc · Japanese presentation copy of the top-level documentation. · `README.ja.md`
- [README ko](https://github.com/zanwei/design-dna/blob/main/README.ko.md): localized doc · Korean presentation copy of the top-level documentation. · `README.ko.md`
- [README zh-CN](https://github.com/zanwei/design-dna/blob/main/README.zh-CN.md): localized doc · Simplified Chinese presentation copy of the top-level documentation. · `README.zh-CN.md`
- [README zh-TW](https://github.com/zanwei/design-dna/blob/main/README.zh-TW.md): localized doc · Traditional Chinese presentation copy of the top-level documentation. · `README.zh-TW.md`
- [Docs](https://github.com/zanwei/design-dna/tree/main/docs): supplemental docs · Supplemental documentation space supporting the skill. · `docs`
- [References](https://github.com/zanwei/design-dna/tree/main/references): knowledge base · Authoritative technical guidance for schema and generation behavior. · `references`
- **Skill package**: distribution · Packaged repository content consumed by the installer and host agent.

### Other components

- **Design DNA**: json profile · Machine-readable profile capturing design tokens, style, and visual effects.
- **Implementation**: ui artifact · Self-contained generated design implementation, typically HTML/CSS/JS.

## Connections

- Skills CLI → Agent platform: installs · Packages the skill into the host agent environment.
- Skill package → Skills CLI: distributed via · Repository content is consumed as a packaged skill.
- Agent platform → SKILL.md: loads · The host agent reads the operational contract.
- SKILL.md → Schema: binds · SKILL.md directs extraction toward the schema boundary.
- SKILL.md → Gen guide: drives · SKILL.md also governs the generation workflow.
- Visual inputs → Agent platform: provided to · User supplies visual references to the host agent.
- Agent platform → Design DNA: extracts · Analyzes inputs into a structured Design DNA JSON profile.
- Schema → Design DNA: constrains · Defines the fields and shape of the JSON profile.
- Design DNA → Gen guide: feeds · The JSON profile becomes the input to generation policy.
- Gen guide → Implementation: renders · Transforms structured DNA into the final implementation.
- README → SKILL.md: introduces · Top-level documentation points to the skill behavior.
- README es → README: mirrors · Localized documentation mirrors the same content.
- README ja → README: mirrors · Localized documentation mirrors the same content.
- README ko → README: mirrors · Localized documentation mirrors the same content.
- README zh-CN → README: mirrors · Localized documentation mirrors the same content.
- README zh-TW → README: mirrors · Localized documentation mirrors the same content.
- Docs → References: supports · Supplemental docs sit alongside the authoritative references.
- References → Schema: contains · Reference layer holds the schema specification.
- References → Gen guide: contains · Reference layer holds generation policy guidance.
