# Implementation

## Agent Instructions

You are extending the KIRUPA design system. Read index.md and the relevant section first. Edit readable shared sources in ssi/newDesign/src/ and build with .github/tools/build-assets.mjs. Reuse current components, semantic tokens, style registries, and asset/sound contracts. Update system.source.json or bots.source.json, regenerate with tools/build_design_system.mjs, and run both builders with --check plus focused tests. Add independent local previews and explicit provenance for new assets or behaviors. Preserve stable IDs and licenses. Keep generated files reproducible, fixtures fictional, and public manifests free of secrets or private state. Do not merge or deploy unless explicitly authorized.

Follow WCAG 2.2 AA for new or changed content: semantic HTML, keyboard access, visible focus, readable contrast in every theme, text alternatives, labeled controls, and explicit errors. Support zoom/reflow, respect reduced motion, and keep sound optional. Read /design/sections/accessibility.md for acceptance checks. Report unresolved barriers; automated checks alone do not establish conformance.

## Reference

Source files, generated outputs, build commands, validation, and extension procedures.

Start with [index.md](/design/index.md). It is a small routing guide, not the entire asset catalog. Each section has its own `/design/ID.htm` tutorial page, linked from the index, left navigation, and previous/next controls. Fetch only the relevant `/design/sections/ID.md`; each starts with a task-scoped Agent Instructions block and the shared accessibility rule. Separate token, asset, sound, and bot JSON files let an agent ask for the data it needs without loading everything.

Edit shared CSS, JS, and SSI in ssi/newDesign/src/, then run node .github/tools/build-assets.mjs and its --check mode. Commit sources and compiled outputs; deploy only outputs. Style scripts and artwork are not built. Preserve cache-busting versions when changing served assets, including the borrowed CSS/JS URLs in design previews.

Edit system.source.json for shared prose/prompts, components.source.json for the component catalog, illustrations.source.json for illustration evidence and production guidance, and bots.source.json for reviewed profile summaries. After the shared asset build, tools/build_design_system.mjs derives the HTML, section Markdown, inventory, token declarations, theme helpers, component examples, portable illustration SVGs, extracted inline SVGs, and synthesized WAVs. Generated files are checked in because this site serves files; there is no production Node build step.

For a new component, start with the [working component examples](/design/components.htm), reuse their classes and semantic roles, add only the missing behavior, and add a meaningful specimen. Set its zero-based `afterParagraph` to place it beside its explanation. For a new visual style, follow header.shtml's registry, scoped style CSS/JS, icon layers, sound roles, and globe renderer contract. Refresh the real screenshots with `node tools/capture_design_screenshots.mjs`; its manifest records source URLs, modes, dimensions, dates, and hashes separately from the icon inventory.

Run `node tools/build_design_system.mjs`, then `node tools/build_design_system.mjs --check`. The check fails on stale or orphaned generated outputs and records explicit source hashes. Run `node --test tools/design_system.test.mjs` for route/data/source contracts. Start the SSI-aware, read-only preview with `php -S 127.0.0.1:8876 -t . design/index.php`. With Playwright available, run `node tools/design_system.browser.mjs` for rendering, independent themes, audio, downloads, emoji, and keyboard/mobile behavior. Run `node tools/design_catalogs.browser.mjs` for every component variant, illustration, portable font, local search, and no-JavaScript fallback. `DESIGN_BASE_URL` overrides the server; `DESIGN_PLAYWRIGHT_PATH` can point to an existing Playwright module without adding a site dependency.

A release is a reviewed source change, not permission to deploy. Follow the deployment instructions for the requested release only, drift-check against live files before an authorized upload, and preserve the legacy Design Center archive. Do not scrape private state into public manifests.

- Do update the source of truth and regenerate; do not hand-patch a generated inventory or WAV.
- Do keep stable IDs and source links, and document intentional exclusions.
- Do not let a generated helper become an independently maintained implementation.

## Sources

- [.github/tools/build-assets.mjs](https://github.com/kirupa/kirupaWWW/blob/main/.github/tools/build-assets.mjs)
- [tools/build_design_system.mjs](https://github.com/kirupa/kirupaWWW/blob/main/tools/build_design_system.mjs)
- [tools/design_system.test.mjs](https://github.com/kirupa/kirupaWWW/blob/main/tools/design_system.test.mjs)
- [design/system.source.json](https://github.com/kirupa/kirupaWWW/blob/main/design/system.source.json)
- [design/bots.source.json](https://github.com/kirupa/kirupaWWW/blob/main/design/bots.source.json)
- [ssi/newDesign/src/header.shtml](https://github.com/kirupa/kirupaWWW/blob/main/ssi/newDesign/src/header.shtml)
- [ssi/newDesign/src/kirupa.js](https://github.com/kirupa/kirupaWWW/blob/main/ssi/newDesign/src/kirupa.js)

[Section page and specimens](/design/extend.htm) | [Instruction index](/design/index.md) | [Plain prompt](/design/agent/extend.txt)