mmorerasanchez · mmorerasanchez · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -102,6 +102,29 @@ Compose ui/ primitives into atoms/molecules; never rebuild from scratch.
 
 ---
 
+## Commit Convention
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/) with design system scopes. Full spec in `CONTRIBUTING.md`.
+
+```
+<type>(<scope>): <description>
+```
+
+Types: `feat` | `fix` | `docs` | `style` | `refactor` | `chore` | `perf` | `test`
+
+Scopes: `tokens` | `atoms` | `molecules` | `organisms` | `templates` | `ui` | `theme` | `deps` | `pages`
+
+Rules: lowercase, imperative mood, no period, under 72 characters. Describe **what changed**, not what you did.
+
+```
+feat(atoms): add Spinner component
+fix(organisms): correct table overflow on mobile
+chore(deps): bump vite from 4.5 to 5.0
+perf(theme): reduce CSS custom property count by 12
+```
+
+---
+
 ## Boundaries
 
 ### ✅ Always allowed

@@ -80,24 +80,7 @@ Follow `CONTRIBUTING.md` for commit conventions and branch naming.
 **Never commit directly to `main`.** Always create a feature branch (`feat/`, `fix/`, `chore/`),
 commit there, then create a PR.
 
-### Notion status sync
-
-Every change request in `changes @democrito` has a Status property that must stay
-in sync with development progress:
-
-1. **When you start work** on a change request — set its Status to **In progress**
-   via Notion MCP before writing any code.
-2. **When you create a PR** — set its Status to **Review** via Notion MCP immediately
-   after the PR is created.
-
-The same applies to `docs @democrito` when working directly on a doc.
-
-Do not skip these transitions. They are how the project owner tracks progress
-without asking.
-
----
-
-> Maintainers track work in a private Notion workspace. Internal access only.
+Commit message format: `<type>(<scope>): <description>` — see `CONTRIBUTING.md` for the full spec with types, scopes, and examples.
 
 ---
 

@@ -49,29 +49,71 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) scoped to
 ### Format
 
 ```
-<type>(<scope>): <short description>
+<type>(<scope>): <description>
 ```
 
+### Types
+
+| Type | Use for |
+| --- | --- |
+| `feat` | New feature or component |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace — no logic change |
+| `refactor` | Restructure without behavior change |
+| `chore` | Dependencies, config, tooling |
+| `perf` | Performance improvement |
+| `test` | Adding or fixing tests |
+
+### Scopes
+
+- `atoms`, `molecules`, `organisms`, `templates` — component layers
+- `ui` — shadcn/ui primitives
+- `tokens` — design tokens (`src/index.css` `@theme` block)
+- `theme` — theme switching, CSS cascade, or multi-theme behavior
+- `pages` — route pages
+- `deps` — dependency updates
+- No scope needed for cross-cutting changes (`docs:`, `chore:`, `ci:`)
+
+### Description rules
+
+- **Lowercase** — `add spinner` not `Add Spinner`
+- **Imperative mood** — `add` not `added`, `fix` not `fixes`
+- **No period at the end**
+- **Under 72 characters**
+- Describe **what changed**, not what you did — `feat(atoms): add Spinner component` not `feat(atoms): created the spinner I needed for loading states`
+
 ### Examples
 
-| Commit | Description |
+| Commit | What it covers |
 | --- | --- |
 | `feat(atoms): add Tooltip atom component` | New atom component |
 | `feat(molecules): add CopyButton molecule` | New molecule component |
-| `fix(organisms): fix DataTable sort order` | Bug fix in an organism |
-| `feat(tokens): add --spacing-2xs token` | New design token |
+| `fix(organisms): correct DataTable sort order on mobile` | Bug fix |
+| `feat(tokens): add warm-theme semantic color aliases` | New design token |
 | `refactor(templates): simplify EditorLayout grid` | Code refactor |
 | `docs: update README architecture tree` | Documentation only |
-| `chore: upgrade tailwindcss to 3.5` | Tooling / dependency updates |
+| `chore(deps): bump vite from 4.5 to 5.0` | Dependency update |
+| `perf(theme): reduce CSS custom property count by 12` | Performance |
 | `test(molecules): add SearchBar unit tests` | Test additions |
+| `style(molecules): fix trailing whitespace in SearchBar` | Formatting only |
 
-### Scopes
+#### ❌ Don't write
 
-- `atoms`, `molecules`, `organisms`, `templates` — component layers
-- `ui` — shadcn/ui primitives
-- `tokens` — design tokens (`index.css`, `tailwind.config.ts`)
-- `pages` — route pages
-- No scope for cross-cutting changes (`docs:`, `chore:`, `ci:`)
+```
+update stuff
+fix things
+🎨 styling
+Add new organisms section
+```
+
+#### ✅ Write
+
+```
+fix(warm-theme): correct --surface token to match design spec
+feat(molecules): add SearchBar with keyboard navigation
+refactor(atoms): rename Tag to Badge for shadcn consistency
+```
 
 ---
 
@@ -143,10 +185,25 @@ Add your component to the layer's `index.ts`:
 export { YourComponent } from "./YourComponent";
 ```
 
-### 7. Submit a pull request
+### 7. Pre-PR checklist
+
+Before submitting, confirm every item below:
+
+- [ ] Component placed in the correct Atomic Design layer (`atoms/`, `molecules/`, `organisms/`, or `templates/`)
+- [ ] Uses CSS custom properties exclusively — no hardcoded hex, RGB, or Tailwind color names (e.g., no `bg-gray-800`, no `text-white`)
+- [ ] Typography: `font-display` for headings/labels, `font-body` for prose, `font-mono` for ALL data, code, and user-editable content
+- [ ] Theme-aware: visually verified in all three themes (Warm, Dark, Light) using the theme toggle on `/tokens`
+- [ ] Responsive: tested at 375px, 768px, and 1280px viewport widths
+- [ ] Accessible: keyboard navigable, `aria-label` added where icon-only or ambiguous
+- [ ] Exported from the layer's `index.ts` barrel file
+- [ ] Added to the showcase page for its layer (`src/pages/<layer>Page.tsx`)
+- [ ] Test file added or updated in `src/test/` (run `npm test` to verify passing)
+- [ ] Entry added to `docs/components/<layer>.md`
+
+### 8. Submit a pull request
 
 - Use a clear title following the commit convention: `feat(molecules): add CopyButton molecule`
-- Describe **what** you added, **why**, and include a screenshot if visual
+- Describe **what** you added, **why**, and include a screenshot showing all three themes
 - Reference any related issues
 
 ---
@@ -159,14 +216,15 @@ Design tokens are the foundation of the visual system. Changes to tokens affect
 
 | File | Role |
 | --- | --- |
-| `src/index.css` | CSS custom properties (source of truth), three-theme definitions |
-| `tailwind.config.ts` | Tailwind mappings to CSS variables |
+| `src/index.css` | CSS custom properties + `@theme` block (source of truth). All token definitions and Tailwind v4 mappings live here. |
+
+> **Tailwind v4 is CSS-first.** There is no `tailwind.config.ts` — it was removed in v3.1.0. All token-to-utility mappings are declared in the `@theme` block inside `src/index.css`.
 
 ### How to propose a token change
 
 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
+2. **Update `src/index.css`** — add the CSS custom property in all three theme blocks (`:root`, `.dark`, `.light`)
+3. **Add a `@theme` mapping** in `src/index.css` if the token needs a Tailwind utility class
 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

diff --git a/DESIGN.md b/DESIGN.md
@@ -368,8 +368,8 @@ All depth comes from the surface hierarchy, not from shadows:
   size changes
 - **Honor the mono contract** — if it's editable, copyable, or
   referenceable, it's `font-mono`
-- **Define tokens before using them** — add to `src/index.css` first,
-  then map in `tailwind.config.ts`, then use in components
+- **Define tokens before using them** — add to `src/index.css` first
+  (both the CSS custom property and the `@theme` mapping), then use in components
 - **Test in all three themes** — Warm (default), Dark, and Light
 - **Use Radix UI / shadcn/ui primitives** for all interactive
   elements — extend via CVA variants, never rebuild

@@ -1,4 +1,4 @@
-# ⚛️ democrito
+# democrito
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript&logoColor=white)
@@ -76,7 +76,7 @@ The skill bundles four knowledge files — `principles.md`, `tokens.md`, `compon
 
 ## For Designers — Retheme Without Code
 
-democrito is designed to be fully customizable through natural language. The entire visual identity lives in CSS custom properties in `src/index.css` and font definitions in `tailwind.config.ts` — which means any AI tool can read and rewrite them from a plain description of your brand.
+democrito is designed to be fully customizable through natural language. The entire visual identity lives in CSS custom properties and font definitions inside `src/index.css` (the `@theme` block) — which means any AI tool can read and rewrite them from a plain description of your brand.
 
 Three paths to make it yours:
 
@@ -294,4 +294,4 @@ terms, attribution guidance, and the paid kit license summary.
 
 ---
 
-Built with ❤️ from 🇪🇸
+Made in Spain · MIT License · Maintained by [@mmorerasanchez](https://github.com/mmorerasanchez)