# Nana OS

## identity

{
  "system": "nanaOS Design System",
  "category": "AI-native, code-first design operating system",
  "creator": {
    "name": "Nana",
    "handle": "nanacodesign",
    "role": "Product designer and design-system author",
    "relationship": "Creator and maintainer of nanaOS",
    "pointOfView": "A design system is a codesign system: shared intent should remain legible to both humans and machines.",
    "profile": "https://github.com/nanacodesign"
  },
  "purpose": "Turn shared product intent into one traceable source of truth for people, products, and agents."
}

## retrieval

Choose the lowest-cost representation that can answer the task.

/llms.txt

text/plain — Fast orientation and read order.

/agent.json

application/json — Canonical public machine manifest.

/agent

text/html — Semantic, text-first Agent Interface.

/#index

text/html — Human-visible System Index search.

authorized package lookup

• contracts/tokens.json
• contracts/components.json
• contracts/constraints.json
• contracts/taxonomy.json
• contracts/recommendations.json
• ADOPTION.md

## architecture

base → primitives → semantics → (rules ∥ capabilities) → components → patterns

base

Non-emitting utilities and reset.

primitives

Raw values; forbidden as component dependencies.

semantics

Intent-bearing tokens consumed by components.

rules

Enforceable accessibility and system laws.

capabilities

Reusable behavior adapters parallel to rules.

components

Recipe-backed production UI.

patterns

Recommended public-API compositions.

## operating_instructions

1. Understand the product anatomy, repeated needs, states, and accessibility constraints before naming a token or component.
2. Determine intent before choosing a visual treatment.
3. Prefer measured primitives and compatible semantic aliases so the vocabulary can grow without renaming existing decisions.
4. Search the inventory and recommendations before proposing a token, component, or pattern.
5. Components consume semantic tokens only; primitive tokens are not component APIs.
6. Respect the downward-only layer dependency rule.
7. Treat generated contracts as read-only projections of authored source.
8. Use public component APIs when composing patterns.
9. Do not invent missing system facts; ask Nana when confidence is below 0.75 or a new system primitive is required.

## transformation_graph

1. 01intent
2. 02recipe
3. 03validation
4. 04generation
5. 05documentation
6. 06audit
7. 07versioned distribution

## source_precedence

1. Active canon
2. Authored source and component recipes
3. Generated contracts
4. Canonical examples
5. Historical ADRs for rationale

## access_boundary

{
  "publicWebsite": true,
  "implementation": "proprietary",
  "package": "authorized consumers only",
  "boundary": "The public manifest explains the system without publishing private implementation contracts."
}