How zanwei/design-dna works
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 README · SKILL.md SKILL.md · generation-guide.md Gen guide · references References
Components 17
External runtime
Host-side agent platform, installer, and visual inputs that consume the skill.
- Agent platform · External agent environment that loads and executes the skill instructions.
- Skills CLI · npx-based installer/distribution boundary for packaging the skill into the host environment.
- Visual inputs · 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 · Operational contract that tells the host agent how to run the skill.
SKILL.md - Schema · Authoritative definition of the Design DNA JSON structure and required fields.
references/schema.md - Gen guide · Rules for turning Design DNA JSON into a working design implementation.
references/generation-guide.md - README · Primary usage and concept documentation.
README.md - README es · Spanish presentation copy of the top-level documentation.
README.es.md - README ja · Japanese presentation copy of the top-level documentation.
README.ja.md - README ko · Korean presentation copy of the top-level documentation.
README.ko.md - README zh-CN · Simplified Chinese presentation copy of the top-level documentation.
README.zh-CN.md - README zh-TW · Traditional Chinese presentation copy of the top-level documentation.
README.zh-TW.md - Docs · Supplemental documentation space supporting the skill.
docs - References · Authoritative technical guidance for schema and generation behavior.
references - Skill package · Packaged repository content consumed by the installer and host agent.
Other components
- Design DNA · Machine-readable profile capturing design tokens, style, and visual effects.
- Implementation · Self-contained generated design implementation, typically HTML/CSS/JS.
Connections 19
- 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.