`design-system/README.md`

36 lines
# HomesOnSpec — Claude Design system bundle

This directory is the **source bundle** for the HomesOnSpec design system on
`claude.ai/design`. It is pushed via the **DesignSync** tool (list → finalize_plan →
write_files), one component at a time.

## Contract
- These previews are the **canonical reference** for `apps/web/src/app/globals.css`
  `@theme`. The swatches show an illustrative subset of each ramp (not every 50–950 stop),
  but the hex values that appear MUST match `globals.css` exactly — change a shared token in
  both, or in neither. The component previews are reference renderings, not a byte-for-byte
  copy of the React components (e.g. the home-card preview shows a photo slot the current
  `SearchClient` card omits).
- Every preview's **first line** is `<!-- @dsCard group="…" -->`. The Design System pane
  builds its card index from that marker (no explicit `register_assets` needed).

## Cards
| Path | Group | Renders |
|---|---|---|
| `tokens.html` | Foundations | brand + accent + status ramps, type scale |
| `components/buttons/index.html` | Components | primary / accent / ghost, two sizes |
| `components/badges/index.html` | Components | verified label + status badges |
| `components/home-card/index.html` | Components | listing card (price, beds, verified, builder) |
| `components/map-legend/index.html` | Components | map legend + field on/off toggle |

## Push (blocked on `/login`)
DesignSync needs a `claude.ai` login with design scopes. In this session:
1. `/login` (adds design-system scopes to the token).
2. `DesignSync list_projects` → pick/create the **HomesOnSpec** project (type must be
   `PROJECT_TYPE_DESIGN_SYSTEM`).
3. `finalize_plan` with writes `tokens.html`, `components/**/index.html`, `localDir` = this dir.
4. `write_files` (localPath uploads — contents never enter model context).

Until then the bundle is committed to git and the live app already renders from the same
tokens, so nothing is blocked except the external mirror.