chore(docs): move DESIGN_SYSTEM.md to docs/ and update all references

.github/CODEOWNERS

@@ -15,7 +15,7 @@ README.md                       @mmorerasanchez
 CONTRIBUTING.md                 @mmorerasanchez
 CHANGELOG.md                    @mmorerasanchez
 CLAUDE.md                       @mmorerasanchez
-src/DESIGN_SYSTEM.md            @mmorerasanchez
+docs/design-system.md            @mmorerasanchez
 
 # CI / Tooling
 .github/                        @mmorerasanchez

.gitignore

@@ -25,6 +25,7 @@ dist-ssr
 
 # Lockfiles (npm is the canonical package manager)
 bun.lockb
+bun.lock
 
 # Playwright artifacts
 playwright-report/

AGENTS.md

@@ -147,5 +147,5 @@ Classify a component before writing it. If you can't classify it, don't build it
 | `docs/ai-context.md` | Reading order + AI bias table (read first) |
 | `docs/tokens.md` | Full token reference |
 | `docs/theming.md` | How to customize for a specific brand |
-| `src/DESIGN_SYSTEM.md` | Full component inventory |
+| `docs/design-system.md` | Full component inventory |
 | `CONTRIBUTING.md` | Commit conventions, branch naming, component creation guide |

CLAUDE.md

@@ -127,7 +127,7 @@ Available test commands:
 |---|---|
 | `src/index.css` | CSS custom properties + CSS-first `@theme` — source of truth for all design tokens and Tailwind integration |
 | `docs/theming.md` | How to customize the system for a specific brand or product |
-| `src/DESIGN_SYSTEM.md` | Full design system specification and component inventory |
+| `docs/design-system.md` | Full design system specification and component inventory |
 | `DESIGN.md` | Design philosophy and visual language — the "taste layer" for AI agents |
 | `CONTRIBUTING.md` | Development workflow, commit conventions, component creation guide |
 | `CHANGELOG.md` | Version history (Keep a Changelog format) |

CONTRIBUTING.md

@@ -167,7 +167,7 @@ Design tokens are the foundation of the visual system. Changes to tokens affect
 1. **Open an issue first** describing the token you want to add, modify, or remove — and why
 2. **Update `src/index.css`** with the new token in all three themes (`:root` dark, `.light`, `.warm`)
 3. **Update `tailwind.config.ts`** if the token needs a Tailwind utility class
-4. **Update `src/DESIGN_SYSTEM.md`** to document the new token
+4. **Update `docs/design-system.md`** to document the new token
 5. **Test visually** across all three themes using the theme toggle in the showcase (`/tokens`)
 6. Submit a PR with before/after screenshots showing all three themes
 

DESIGN.md

@@ -11,7 +11,7 @@
 >
 > **Complements, does not replace:**
 > - `CLAUDE.md` — agent coding rules and project structure
-> - `src/DESIGN_SYSTEM.md` — full token inventory and component spec
+> - `docs/design-system.md` — full token inventory and component spec
 > - `docs/tokens.md` — exhaustive color/type/spacing reference
 >
 > This file is the *taste layer*; those files are the *vocabulary*.
@@ -513,7 +513,7 @@ bg-primary (if not the most important action on screen).
 
 When making a visual decision while working in democrito:
 
-1. Does `src/DESIGN_SYSTEM.md` already answer this? → Use that.
+1. Does `docs/design-system.md` already answer this? → Use that.
 2. Does the three-surface hierarchy handle the depth? → If no,
    reconsider the layout.
 3. Is a fourth font being introduced? → Stop. Three is the limit.
@@ -535,7 +535,7 @@ and tools. This is how they relate:
 |------|------|----------|
 | `DESIGN.md` (this file) | Design philosophy, visual taste, agent prompt guide | AI agents (Stitch, Claude, Cursor), designers |
 | `CLAUDE.md` | Coding rules, project structure, key files | AI coding agents (Claude Code, Cursor, Windsurf) |
-| `src/DESIGN_SYSTEM.md` | Full token inventory, component spec, every value | Developers, component authors |
+| `docs/design-system.md` | Full token inventory, component spec, every value | Developers, component authors |
 | `docs/tokens.md` | Color/type/spacing reference with examples | Developers, designers |
 | `docs/theming.md` | How to customize for your brand | Developers adopting democrito |
 | `docs/architecture.md` | Why Atomic Design, folder structure, composition rules | Contributors |
@@ -546,7 +546,7 @@ and tools. This is how they relate:
 
 1. `src/index.css` — token values (the source of truth)
 2. `DESIGN.md` — philosophy wins on intent questions
-3. `src/DESIGN_SYSTEM.md` — spec wins on component details
+3. `docs/design-system.md` — spec wins on component details
 4. `CLAUDE.md` — rules win on coding conventions
 5. `docs/` files — extended reference
 

README.md

@@ -267,7 +267,7 @@ IDE-inspired, clean, distraction-free aesthetic.
 | --- | --- |
 | [Live Design System](https://democrito.design) | Interactive component gallery, token reference, and theme playground |
 | [`docs/theming.md`](docs/theming.md) | How to customize the system for your brand — palette, fonts, spacing, with full examples |
-| [`src/DESIGN_SYSTEM.md`](src/DESIGN_SYSTEM.md) | Complete design system specification — component inventory, token reference, usage rules |
+| [`docs/design-system.md`](docs/design-system.md) | Complete design system specification — component inventory, token reference, usage rules |
 | [`src/index.css`](src/index.css) | CSS custom properties + Tailwind v4 `@theme` — source of truth for all tokens |
 | [`design-tokens.json`](design-tokens.json) | W3C DTCG–format tokens for tooling interoperability (Figma, Style Dictionary) |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution guidelines, commit conventions, and component creation workflow |