Design Frameworks
Announce at start: "I'm using the humane:design-frameworks skill to fit this implementation to the project's existing design system without changing the product decision above it."
This skill is an implementation adapter. It translates a settled-enough design decision into the components, patterns, tokens, themes, templates, and checks an existing system actually provides. It does not decide what the product should be.
The Humane method stays above every preset:
job → evidence → concept → prototype → review → learning
A preset may report that the system cannot express the accepted concept. It may not silently alter the job, acceptance criteria, content hierarchy, interaction model, or prototype to make the available components look sufficient.
Quick Reference
| Need | Read |
|---|---|
| Preset profiles, selection, and fallback behavior | references/presets.md |
| Common objects, capability rules, fit-plan and finding shapes | references/contract.md |
| Astryx native CLI/API commands and write boundaries | references/astryx.md |
| shadcn registry, CLI/MCP, and source-ownership boundaries | references/shadcn.md |
| Storybook manifests/MCP as a project-local catalog and test overlay | references/storybook.md |
Read only the selected preset reference. Read contract.md when producing a
machine-readable manifest, fit plan, operation receipt, or validation result.
1. Establish the implementation brief
Before touching the framework, name the immutable inputs you are fitting:
- the job or outcome reference;
- the evidence references supporting it;
- the accepted concept and acceptance criteria;
- the prototype or existing implementation being fitted;
- unresolved decisions and review findings that remain open.
References are enough; do not copy the whole Humane corpus into an adapter object. If these inputs do not exist, ordinary framework help can still proceed, but label Humane traceability Not available. Never invent research or claim that a framework-compliant build has validated the product idea.
2. Select, then verify, a preset
The user's explicit preset wins. Otherwise inspect the project read-only:
package.json, lockfile, framework config, component directories, token files,
Storybook config, MCP configuration, and installed local binaries. Use the
selection table in presets.md.
A preset name is a bootstrap hint, not proof. Probe the native surface and record what this version and project actually expose. If the probe contradicts the preset reference, the probe wins and the difference is a limitation. Never guess a capability from the system's brand or from a remembered release.
Prefer authoritative surfaces in this order when several expose the same fact:
- a project-local machine manifest or documented programmatic API;
- typed JSON from the system's installed CLI;
- a schema-governed registry or generated project manifest;
- negotiated MCP tools and resources;
- installed package types and authored project documentation;
- remote prose documentation, as a cited fallback only.
Do not download a CLI, start a server, connect a remote registry, or install an MCP server merely to probe. Those are separate network or installation actions and need the user's approval.
3. Discover before composing
Build a small catalog for the requested scope, not a dump of the whole system. Inspect the native IDs, import paths, props, examples, variants, dependencies, token requirements, theme behavior, and ownership model of likely resources.
Keep provenance attached. A normalized Button without its package, registry,
version, or source locator is not safe evidence. Preserve native fields the
adapter does not understand; for DTCG tokens, never infer type or purpose from a
group name and never discard unknown extensions.
4. Produce a fit plan before a patch
Map the implementation brief to native resources and return:
- the selected components, patterns, templates, themes, and tokens;
- how each choice serves an acceptance criterion or prototype behavior;
- proposed commands and file operations, with exact targets;
- conflicts and deviations, including capabilities the framework lacks;
- the native checks that will run after implementation;
- anything that remains Not verified or Not supported.
Planning is read-only. If a native preview or diff exists, use it. Otherwise the operation is not safely applicable through this skill until an exact preview can be produced another way.
5. Apply only an approved preview
Show the preview and ask before the first write. Approval covers only the shown operations. Re-plan if a command resolves different files, dependencies, environment variables, configuration, or migrations at execution time.
Always use the framework's supported CLI or public API for framework-owned changes. Ordinary application source that composes public framework components may use the project's normal editing path, but only after an exact file diff is part of the approved preview. Do not reproduce the framework's installer, registry resolver, codemod, or theme compiler in this skill. Capture the native receipt or the resulting diff.
These operations are never implicit: dependency installation, network fetches,
--force/overwrite, eject/swizzle, codemods or migrations, theme replacement,
agent-instruction edits, lockfile changes, generated-file writes, and deletion.
6. Validate in two lanes
Framework compliance and Humane validity are different claims.
Framework lane: run only checks the discovered system actually provides — schema validation, doctor/integration checks, type generation and type-checking, builds, story interaction tests, accessibility checks, token/reference checks, or project tests. Record the command/tool and evidence.
Humane lane: trace the result back to the implementation brief. Confirm that the accepted job, concept, hierarchy, interactions, and prototype behavior did not drift during adaptation. Product review and learning still belong to their own Humane owners; this lane checks traceability, not whether the product idea was good.
Use pass, fail, warn, not-run, or not-supported. Unsupported and
unrun checks are never passes. A clean build does not prove usability, and a
successful review does not prove framework compliance.
Never override
- Humane corpus, evidence, concept, prototype notes, review findings, or learning artifacts;
- accepted product intent, information hierarchy, interaction model, or copy;
- project tokens, themes, framework config, agent instructions, or lockfiles;
- source-owned, ejected, swizzled, or manually modified components;
- generated files or unrelated source;
- secrets, credentials, registry tokens, or environment values;
- unknown registry metadata or DTCG extensions;
- an accessibility requirement to make a preset fit.
When the framework and the implementation brief conflict, stop at the fit plan and name the decision the user must make. The adapter does not get a tie-breaker.
Output
For read-only discovery, return Preset, Observed capabilities, Resources inspected, Limitations, and Next safe action.
For implementation, return the Fit plan, the approved Operation
receipts, and Validation split into Framework and Humane lanes. State every
write and every check not run. Then offer the declared handoff to
humane:review; do not run it automatically.
Use these fit-plan headings so a human can approve the boundary without reading the contract JSON: Brief refs, Preset and observed version, Selected native resources, Criterion mapping, Exact proposed operations, Conflicts and deviations, Checks after apply, Not verified, and Approval needed.
