# paglaai/pagladesign architecture

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

- Interactive diagram: https://gitdiagram.com/paglaai/pagladesign
- Repository: https://github.com/paglaai/pagladesign

## Overview

PaglaDESIGN is a canonical, machine-readable design authority, not an application or component kit. Its workflow starts with design doctrine, tokens, specifications, and ecosystem registry; those assets guide downstream surfaces and agents through CSS, human-facing FERN documentation, machine-readable/MCP access, and architecture governance. The README documents these product branches, while the sampled source mainly exposes the FERN and DOCX generators. The MCP implementation and several renderer details are not sampled, so their internal relationships are not expanded.

Main entry points: [`css/tokens.css`](https://github.com/paglaai/pagladesign/blob/main/css/tokens.css) (Reference CSS), [`design-system/DESIGN_TOKENS.md`](https://github.com/paglaai/pagladesign/blob/main/design-system/DESIGN_TOKENS.md) (Design Tokens), [`bin/build_fern.py`](https://github.com/paglaai/pagladesign/blob/main/bin/build_fern.py) (FERN Renderer), [`design-system/DESIGN_DNA.md`](https://github.com/paglaai/pagladesign/blob/main/design-system/DESIGN_DNA.md) (Design DNA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authority["Design Authority"]
  node_design_dna["Design DNA<br/>[DESIGN_DNA.md]"]
  node_design_tokens["Design Tokens<br/>[DESIGN_TOKENS.md]"]
  node_component_specs["Component Specs"]
  node_brand_guidance["Brand Guidance<br/>[BRAND.md]"]
  node_ecosystem_registry[("Ecosystem Registry<br/>[ecosystem.json]")]
end

subgraph group_surfaces["Human Surfaces"]
  node_reference_css["Reference CSS<br/>[tokens.css]"]
  node_css_layers["CSS Layers<br/>[base.css]"]
  node_css_utilities["CSS Utilities<br/>[utilities.css]"]
  node_fern_renderer["FERN Renderer<br/>[build_fern.py]"]
  node_docs_portal["Documentation Portal"]
  node_docx_generator["DOCX Generator<br/>[build_docx.py]"]
end

subgraph group_machine["Machine Access"]
  node_machine_renderer["Machine Renderer"]
  node_mcp_server["MCP Retrieval<br/>[server.py]"]
  node_rag_indexer["RAG Indexer<br/>[rag.py]"]
end

subgraph group_governance["Governance"]
  node_architecture_specs["Architecture Specs"]
  node_adr_governance["ADR Governance<br/>[DECISIONS.md]"]
end

node_downstream_surfaces(("Downstream Surfaces"))
node_ai_agents(("AI Agents"))

node_design_tokens -->|"defines tokens"| node_reference_css
node_reference_css -->|"styles surfaces"| node_css_layers
node_reference_css -->|"styles surfaces"| node_css_utilities
node_design_dna -->|"guides implementation"| node_downstream_surfaces
node_component_specs -->|"specifies components"| node_downstream_surfaces
node_brand_guidance -->|"guides identity"| node_downstream_surfaces
node_ecosystem_registry -->|"registers consumers"| node_downstream_surfaces
node_fern_renderer -->|"generates portal"| node_docs_portal
node_design_tokens -->|"informs styling"| node_fern_renderer
node_machine_renderer -->|"provides context format"| node_ai_agents
node_mcp_server -->|"serves retrieval"| node_ai_agents
node_rag_indexer -->|"grounds retrieval"| node_ai_agents
node_architecture_specs -->|"formalizes decisions"| node_adr_governance

click node_design_dna "https://github.com/paglaai/pagladesign/blob/main/design-system/DESIGN_DNA.md"
click node_design_tokens "https://github.com/paglaai/pagladesign/blob/main/design-system/DESIGN_TOKENS.md"
click node_component_specs "https://github.com/paglaai/pagladesign/blob/main/components/COMPONENT_LIBRARY.md"
click node_brand_guidance "https://github.com/paglaai/pagladesign/blob/main/brand/BRAND.md"
click node_ecosystem_registry "https://github.com/paglaai/pagladesign/blob/main/ecosystem.json"
click node_reference_css "https://github.com/paglaai/pagladesign/blob/main/css/tokens.css"
click node_css_layers "https://github.com/paglaai/pagladesign/blob/main/css/base.css"
click node_css_utilities "https://github.com/paglaai/pagladesign/blob/main/css/utilities.css"
click node_fern_renderer "https://github.com/paglaai/pagladesign/blob/main/bin/build_fern.py"
click node_docs_portal "https://github.com/paglaai/pagladesign/tree/main/DOC"
click node_docx_generator "https://github.com/paglaai/pagladesign/blob/main/bin/build_docx.py"
click node_machine_renderer "https://github.com/paglaai/pagladesign/blob/main/design-system/MACHINE_RENDERER.md"
click node_mcp_server "https://github.com/paglaai/pagladesign/blob/main/.ai/mcp/server.py"
click node_rag_indexer "https://github.com/paglaai/pagladesign/blob/main/.ai/mcp/rag.py"
click node_architecture_specs "https://github.com/paglaai/pagladesign/blob/main/design-system/ARCHITECT_RENDERER.md"
click node_adr_governance "https://github.com/paglaai/pagladesign/blob/main/governance/DECISIONS.md"

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_design_dna,node_design_tokens,node_component_specs,node_brand_guidance,node_ecosystem_registry toneBlue
class node_reference_css,node_css_layers,node_css_utilities,node_fern_renderer,node_docs_portal,node_docx_generator toneAmber
class node_machine_renderer,node_mcp_server,node_rag_indexer toneMint
class node_architecture_specs,node_adr_governance toneRose
class node_downstream_surfaces,node_ai_agents toneIndigo
```

## Components

### Design Authority

- [Design DNA](https://github.com/paglaai/pagladesign/blob/main/design-system/DESIGN_DNA.md): `design-system/DESIGN_DNA.md`
- [Design Tokens](https://github.com/paglaai/pagladesign/blob/main/design-system/DESIGN_TOKENS.md): `design-system/DESIGN_TOKENS.md`
- [Component Specs](https://github.com/paglaai/pagladesign/blob/main/components/COMPONENT_LIBRARY.md): `components/COMPONENT_LIBRARY.md`
- [Brand Guidance](https://github.com/paglaai/pagladesign/blob/main/brand/BRAND.md): `brand/BRAND.md`
- [Ecosystem Registry](https://github.com/paglaai/pagladesign/blob/main/ecosystem.json): `ecosystem.json`

### Human Surfaces

- [Reference CSS](https://github.com/paglaai/pagladesign/blob/main/css/tokens.css): `css/tokens.css`
- [CSS Layers](https://github.com/paglaai/pagladesign/blob/main/css/base.css): `css/base.css`
- [CSS Utilities](https://github.com/paglaai/pagladesign/blob/main/css/utilities.css): `css/utilities.css`
- [FERN Renderer](https://github.com/paglaai/pagladesign/blob/main/bin/build_fern.py): `bin/build_fern.py`
- [Documentation Portal](https://github.com/paglaai/pagladesign/tree/main/DOC): `DOC`
- [DOCX Generator](https://github.com/paglaai/pagladesign/blob/main/bin/build_docx.py): `bin/build_docx.py`

### Machine Access

- [Machine Renderer](https://github.com/paglaai/pagladesign/blob/main/design-system/MACHINE_RENDERER.md): `design-system/MACHINE_RENDERER.md`
- [MCP Retrieval](https://github.com/paglaai/pagladesign/blob/main/.ai/mcp/server.py): `.ai/mcp/server.py`
- [RAG Indexer](https://github.com/paglaai/pagladesign/blob/main/.ai/mcp/rag.py): `.ai/mcp/rag.py`

### Governance

- [Architecture Specs](https://github.com/paglaai/pagladesign/blob/main/design-system/ARCHITECT_RENDERER.md): `design-system/ARCHITECT_RENDERER.md`
- [ADR Governance](https://github.com/paglaai/pagladesign/blob/main/governance/DECISIONS.md): `governance/DECISIONS.md`

### Other components

- **Downstream Surfaces**
- **AI Agents**

## Connections

- Design Tokens → Reference CSS: defines tokens (evidence: `README.md`)
- Reference CSS → CSS Layers: styles surfaces (evidence: `README.md`)
- Reference CSS → CSS Utilities: styles surfaces (evidence: `README.md`)
- Design DNA → Downstream Surfaces: guides implementation (evidence: `README.md`)
- Component Specs → Downstream Surfaces: specifies components (evidence: `README.md`)
- Brand Guidance → Downstream Surfaces: guides identity (evidence: `README.md`)
- Ecosystem Registry → Downstream Surfaces: registers consumers (evidence: `README.md`)
- FERN Renderer → Documentation Portal: generates portal (evidence: `README.md`)
- Design Tokens → FERN Renderer: informs styling (evidence: `README.md`)
- Machine Renderer → AI Agents: provides context format (evidence: `README.md`)
- MCP Retrieval → AI Agents: serves retrieval (evidence: `README.md`)
- RAG Indexer → AI Agents: grounds retrieval (evidence: `README.md`)
- Architecture Specs → ADR Governance: formalizes decisions (evidence: `README.md`)
