@huynh-os/components

The canonical component and block specs for Huynh OS, stored as data.

Components are specced here and built later (as @huynh-os/react). This package is the ground truth that design, code, Figma, and agents all read from — authored before any framework implementation exists.

What lives here

specs/
  button.json        ComponentSpec
  card.json
  input.json
  badge.json
  nav-item.json
  toast.json
  blocks/
    hero-band.json   BlockSpec
    expressive-section.json
    data-panel.json

Each file is a ComponentSpec or BlockSpec as defined in @huynh-os/schema. A spec carries its full contract: anatomy, variants, required states, token bindings, accessibility, motion roles, content rules, slots, and the human usage contract (when to use / when not / dos / don'ts).

The build is a contract gate

pnpm build runs scripts/build.mjs, which fails if any of these are violated:

1. Schema validation — every spec must satisfy validateComponentSpec / validateBlockSpec.
2. Token bindings resolve — every tokenBinding.tokenPath must resolve to a real token (leaf or group) in the @huynh-os/tokens manifest. This is what stops a spec referencing a token that has been renamed or removed.
3. Reference integrity — every block componentRefs id and every slot allowedComponents id must name a known component spec.

On success it emits dist/manifest.json ({ components, blocks }) for agents and tooling, exported as @huynh-os/components/manifest.

Usage

import { loadComponentSpecs, loadComponentSpec, loadBlockSpecs } from '@huynh-os/components'

const button = loadComponentSpec('button')
const allBlocks = loadBlockSpecs()

The loaders validate on read and throw on an invalid spec, so a consumer never receives a malformed spec.

Adding a component

1. Add specs/<id>.json following an existing spec.
2. Bind every styled property to a token path that exists in @huynh-os/tokens.
3. pnpm build — the gates tell you immediately if a binding or reference is wrong.