# nodes

id: foundation:layouts-contract
type: layouts-contract
name: Layout primitives contract
path: base/layouts.md
data: {}
body:
# Layout Contract

Load this file before writing custom layout CSS. RenDS layouts are public API:
agents should compose with layout primitives first and only write bespoke
layout CSS when the primitive set does not cover the problem.

## Purpose

- Keep page structure consistent across RenDS consumers.
- Avoid one-off `display: flex` and `display: grid` rules that duplicate the
  foundation.
- Ensure responsive behavior follows the same spacing, width, and container
  rules as the rest of the system.

## Routing Table

| Need | Use | Avoid |
|---|---|---|
| Vertical flow | `ren-stack`, `ren-stack-sm`, `ren-stack-lg` | Custom column flex |
| Inline wrapping group | `ren-cluster` | Custom wrap flex |
| Horizontal row | `ren-row` | Repeated `display:flex; align-items:center` |
| Left/right spread | `ren-row-spread` | Custom `justify-content: space-between` |
| Centered content | `ren-center`, `ren-center-narrow`, `ren-center-wide`, `ren-center-prose` | Fixed width + auto margins |
| Responsive cards | `ren-grid`, `ren-grid-2`, `ren-grid-3`, `ren-grid-4` | Hand-authored repeat grids |
| Sidebar + content | `ren-with-sidebar` | Custom fixed sidebar layout |
| Full-screen centered surface | `ren-cover` | `min-height:100vh` centering |
| Aspect-ratio media | `ren-frame`, `ren-frame-square`, `ren-frame-photo` | Ad hoc aspect wrappers |
| Responsive direction switch | `ren-switcher` | Viewport-only flex swaps |
| Horizontal scroll | `ren-reel` | Raw overflow and scroll snap |

## Required Imports

```html
<link rel="stylesheet" href="rends/index.css">
```

## Rules

- Decide the page skeleton before selecting components.
- Use layout primitives for structure, then place primitives/composites/patterns
  inside them.
- Prefer `gap` on the parent over margins on children.
- Prefer container-query helpers when behavior depends on component width.
- Keep nested layout primitives shallow; flatten structure when possible.
- Use semantic spacing tokens such as `--space-*`, `--space-card-padding`, and
  `--space-section` when a custom value is unavoidable.

## Related Files

- `base/layouts.css` - implementation source of truth.
- `base/grid.css` - grid helpers.
- `base/utilities.css` - small utilities.
- `rends-skill/references/architecture.md` - expanded agent guidance.
- `docs/layouts.html` - visual reference.

## Test Expectations

- Layout changes should keep responsive docs/pages readable at mobile and
  desktop widths.
- Do not add raw layout CSS when an existing primitive can express the same
  structure.


id: foundation:primitive-zero
type: primitive-zero
name: Native HTML contract
path: base/primitive-zero.md
data: {}
body:
# Primitive Zero Contract

Primitive Zero is RenDS' classless layer: native HTML elements styled through
`base/classless.css` before any `ren-` component class is introduced. Load this
file when an agent is about to write semantic HTML, prose content, form
structure, tables, media, or document scaffolding without a component class.

## Purpose

- Preserve browser semantics first: headings, paragraphs, lists, tables, forms,
  media, landmarks, and disclosure elements should be valid native HTML before
  they become RenDS components.
- Provide readable default typography, spacing, focus rings, and reduced-motion
  behavior through tokens.
- Define when a tag graduates from classless HTML into a primitive, composite,
  or pattern.

## Use Primitive Zero When

- The element is meaningful HTML on its own: `h1`, `p`, `a`, `ul`, `ol`,
  `blockquote`, `table`, `fieldset`, `details`, `summary`, `figure`, `code`,
  `pre`, `kbd`, `mark`, `del`, `ins`, landmarks, and form labels.
- The visual behavior can be handled by `base/classless.css` and semantic
  tokens.
- The user benefits from native browser behavior even if JavaScript is disabled.

## Graduate To A Component When

- The element needs a named public API, variants, state, or custom properties.
- Interaction requires ARIA wiring, roving tabindex, focus trapping, dismiss
  behavior, typeahead, live-region announcements, or JS enhancement.
- A repeated UI object needs a `ren-` class so consumers can theme it
  intentionally.

## Required Imports

```html
<link rel="stylesheet" href="rends/index.css">
```

`rends/index.css` imports reset, tokens, base classless styles, layouts, motion
presets, and utilities. Component CSS is not required for Primitive Zero.

## Accessibility Contract

- Use landmarks for structure, not decoration. Primitive Zero applies no visual
  chrome to `header`, `nav`, `main`, `article`, `section`, `aside`, or `footer`.
- Use `:focus-visible` behavior from the foundation; do not remove the focus
  ring.
- Keep body text readable: do not drop below the RenDS minimum type scale.
- Respect `prefers-reduced-motion`; foundation tokens collapse motion before
  component overrides.
- Do not use color alone for state. Pair error/success/warning with text,
  icons, or ARIA where needed.

## Related Files

- `base/classless.css` - implementation source of truth.
- `base/reset.css` - browser normalization.
- `base/motion-alternatives.css` and `base/motion-presets.css` - motion safety.
- `docs/primitive-zero.html` - visual reference and element catalog.
- `_archive/PRIMITIVE-ZERO-A11Y-AUDIT.md` - historical audit context.

## Test Expectations

- `npm run test:a11y` must keep `docs/primitive-zero.html` free of axe
  violations.
- Manual review should cover keyboard focus, headings, links, table captions,
  form labels, `details/summary`, and code/pre wrapping in both light and dark
  themes.


id: foundation:tokens-contract
type: tokens-contract
name: Token contract
path: tokens/tokens.md
data: {}
body:
# Token Contract

Load this file before choosing colors, spacing, typography, radius, shadows,
motion, z-index, or component-level theme overrides.

## Purpose

RenDS uses a three-layer token model:

1. Primitive tokens are raw values: `--blue-500`, `--space-4`,
   `--text-base`, `--radius-md`.
2. Semantic tokens describe intent: `--color-accent`,
   `--color-text-muted`, `--space-card-padding`, `--duration-enter`.
3. Component tokens expose public override points:
   `--ren-btn-bg`, `--ren-card-radius`, `--ren-dialog-width`.

Components consume semantic or component tokens. They do not consume primitive
tokens directly.

## Required Imports

```html
<link rel="stylesheet" href="rends/index.css">
<link rel="stylesheet" href="rends/tokens/component/tokens.css">
```

Use `tokens/component/tokens.css` when a page or component depends on the
component token API.

## Rules

- Use semantic tokens for day-to-day UI values.
- Add a semantic token when an intent is missing; do not hard-code raw values.
- Use component tokens for surgical component theming.
- Do not override semantic tokens inside a component implementation; override
  at `:root`, `[data-theme]`, or a consumer-owned theme scope.
- Use `light-dark()` in the semantic layer; do not write `.dark` patches.
- Use `--color-border-interactive` for actionable control borders.
- Use `--color-*-strong` for status/accent text on neutral surfaces.
- Use `--color-on-*` only on the matching solid background.
- Pair `--color-on-surface-contrast` only with
  `--color-surface-contrast` for editorial surfaces that remain dark in every
  theme.
- Do not use `--color-text-faint` for information the user must read.
- Use semantic motion tokens and transition presets; do not write raw
  durations or easings in components.

## Related Files

- `tokens/primitives/*.css` - raw palettes and scales.
- `tokens/semantic/*.css` - intent-based token layer.
- `tokens/component/tokens.css` - public component override API.
- `tokens/registered-properties.css` - typed CSS custom properties.
- `rends-skill/references/tokens.md` - expanded agent reference.
- `docs/tokens.html` - visual docs page.

## Test Expectations

- CSS lint should pass after token edits.
- Accessibility/a11y checks should pass when color pairings change.
- Any new component value should be expressible as a semantic or component
  token before shipping.


id: tooling:knowledge-graph
type: tooling-doc
name: Knowledge graph tooling
path: docs/knowledge-graph.md
data: {}
body:
# RenDS Knowledge Graph

Local, generated graph for querying RenDS contracts, component source, docs,
examples, selectors, and tokens.

This is both project tooling and a packaged aid for agents that install
`ren10` from npm.

## Why This Shape

- Keep the source of truth in the existing files: contracts, CSS, JS, docs, and
  examples.
- Generate the graph deterministically instead of hand-maintaining a second
  spec.
- Ship a prebuilt SQLite database plus FTS5 for search/querying when the
  `sqlite3` CLI is available.
- Ship a JSON fallback for agents that can read files but cannot open SQLite.
- Avoid `node:sqlite` for now because CI runs Node 20 and Node 22 still marks
  the built-in SQLite API as experimental.
- Avoid `better-sqlite3` for the first cut because it adds a native dependency.

## Commands

```bash
npm run knowledge:build
npm run knowledge:check
npm run knowledge:query -- "ren-toast status"
npm run knowledge:query -- "ren-toast status" --json
npm run agent:manifest
npm run agent:doctor
npm run agent:smoke
npm run agent:skill:check
npm run agent:skill:pack
npm run agent:check
npx ren10 manifest --json
npx ren10 search "dialog workflow" --json
npx ren10 build "dashboard with sidebar" --json
npx ren10 component button --dense
npx ren10 docs layouts --dense
npx ren10 doctor
npx ren10 knowledge
npx ren10 knowledge query "ren-toast status"
npx ren10 knowledge query "ren-toast status" --json
npx ren10 knowledge check
```

Generated and packaged files live in `knowledge/`:

- `knowledge/ren10-graph.json`
- `knowledge/ren10-graph.sqlite`

The generated files are included in the npm package, so an installed consumer
or agent can inspect `node_modules/ren10/knowledge/`.

Agent-facing JSON commands use a stable envelope:

```json
{
  "apiVersion": 1,
  "type": "search",
  "data": {}
}
```

Use `--json` for typed machine output. Use `--dense` when an agent needs a
compact Markdown summary that still points back to source contracts.

`knowledge:check` is the package/release gate. It regenerates the graph into a
temporary directory, compares the fresh JSON with the committed package JSON,
validates the packaged SQLite database logically, and checks that npm pack
includes the graph files.

## Current Schema

Nodes:

- `component`
- `contract`
- `css`
- `javascript`
- `docs_page`
- `example`
- `selector`
- `token`
- foundation contracts such as `design-contract`, `tokens-contract`, and
  `component-router`

Edges:

- `has_contract`
- `has_css`
- `has_js`
- `has_docs_page`
- `exposes_selector`
- `uses_token`
- `used_by_example`

## Current Check Layer

The check currently covers:

- Generated JSON freshness.
- SQLite integrity, row counts, node IDs, edge rows, and an FTS smoke query.
- Component coverage: 19 primitives, 26 composites, 8 patterns.
- Required contract, CSS, and docs edges for every component.
- Selector/token edge consistency.
- npm pack inclusion for `knowledge/README.md`, JSON, and SQLite.
- npm pack inclusion for the agent-ready roadmap, eval README, and versioned
  RenDS skill.
- Agent CLI JSON smoke coverage through `npm run agent:smoke`.

## Intended Next Layer

The next useful step is to make the graph checks more semantic, not only
structural:

- Contract/source drift: selector exists in CSS but not in the contract.
- Token drift: component uses a token not allowed by its contract.
- Docs drift: docs page references stale class names.
- Example coverage: public selectors or variants with no runnable example.
- Agent routing: given a prompt, return the relevant contract chain before
  generation starts.


id: tooling:knowledge-readme
type: tooling-doc
name: Packaged knowledge graph readme
path: knowledge/README.md
data: {}
body:
# RenDS Knowledge Graph

Packaged graph for agents and tools that need to understand RenDS from the
installed `ren10` npm package.

## Files

- `ren10-graph.sqlite` — primary SQLite database with FTS5 search.
- `ren10-graph.json` — fallback graph for agents that can read files but
  cannot open SQLite.

## CLI

```bash
npx ren10 manifest --json
npx ren10 build "dashboard with sidebar" --json
npx ren10 search "ren-toast status" --json
npx ren10 component toast --dense
npx ren10 docs layouts --dense
npx ren10 doctor
npx ren10 knowledge
npx ren10 knowledge query "ren-toast status"
npx ren10 knowledge query "ren-toast status" --json
npx ren10 knowledge check
```

The query command prefers SQLite when the local `sqlite3` CLI is available and
falls back to the packaged JSON graph when it is not.

All agent-facing JSON responses use this envelope:

```json
{
  "apiVersion": 1,
  "type": "knowledge.query",
  "data": {}
}
```

Use `--json` for typed machine output. Use `--source-json` only when you need
to force the packaged JSON graph instead of SQLite.

## What It Contains

Nodes:

- components
- contracts
- CSS files
- JavaScript files
- docs pages
- examples
- selectors
- tokens
- foundation contracts

Edges:

- `has_contract`
- `has_css`
- `has_js`
- `has_docs_page`
- `exposes_selector`
- `uses_token`
- `used_by_example`

This graph is generated from the repository source. Do not edit the generated
SQLite or JSON files by hand.


