agentic-acss-plugins

Warning

Experimental — This project is under active exploration. APIs, commands, and conventions may change significantly between versions. The core idea — replacing npm packages with agent-driven skills — is still being validated, and we expect the approach to evolve as we learn what works best in practice.

A Claude Code plugin marketplace for building accessible React applications with the fpkit/acss design system. Two decoupled plugins, no npm package to add.

What this is: a marketplace of Claude Code plugins — markdown-as-source skills, slash commands, and Python 3 scripts (mostly stdlib-only; acss-kit/scripts/validate_utilities.py uses tinycss2). There is no Node.js build and no publish pipeline; the only GitHub Actions workflows are Claude-driven review automations under .github/workflows/. Plugins drop generated TSX/SCSS/CSS straight into your project using local imports.

Who it's for: developers working in React + TypeScript + Sass projects who want accessible components and a token-driven theming system without taking on a new runtime dependency.

Plugins in this marketplace

Plugin	Version	What it ships
acss-kit	1.8.0	Accessible React components, static HTML snippets, OKLCH CSS themes, and Tailwind-style utility classes for fpkit/acss projects. WCAG 2.2 AA validation built-in.
style-agent	0.5.0	Framework-agnostic CSS authoring skills. /css-to-class extracts utility-class lists into a single named class; /inline-style-to-class converts inline styles or JSX style objects into a named class appended to the project stylesheet; /create-utilities generates a utility-class string from a plain-language description. Works with plain CSS, SCSS, Tailwind, or any utility-first workflow. Also publishes the COMPONENT.md spec — a framework-neutral format for describing a component's structure, props, behavior, and accessibility, themed by a sibling DESIGN.md.

The two plugins are decoupled — install either or both independently.

DESIGN.md + COMPONENT.md — the two-file design system

The format layer underneath both plugins, and the direction this project is heading: a design system described in two plain-markdown files that any coding agent can read and project into real code. There is no runtime, no schema package — just two files coupled through token references.

File	Owns	Format
DESIGN.md	The visual identity — colors, typography, spacing, rounded tokens (plus a freeform components block).	Google Labs design-token format. A primary color is required — it seeds the OKLCH palette.
COMPONENT.md	A single component — its semantic structure, props, behavior, and accessibility contract.	Framework-neutral spec published by style-agent. One file per component (<name>.component.md).

The coupling is the {token.path} reference: a COMPONENT.md names primitives like {colors.primary} or {spacing.sm}, and an agent resolves them against whatever sibling DESIGN.md the project provides. DESIGN.md owns tokens, COMPONENT.md owns components — loosely coupled through the file format, never through shared code. With no DESIGN.md present, every reference falls back to an embedded CSS default (var(--x, <fallback>)), so components still render.

Why it matters: a component's semantic HTML, CSS, and accessibility contract are framework-agnostic web primitives — only template syntax and state binding are framework-specific. COMPONENT.md captures the neutral majority as the source of truth; an agent projects it into React, HTML, Astro, Angular, Vue, Svelte, or a web component, optionally guided by per-target ## Target: <framework> adapter blocks.

How the two plugins integrate around it

• acss-kit is a DESIGN.md bridge — bidirectional.
  • Inbound: /theme-from-design <DESIGN.md> consumes a DESIGN.md and generates the full theme (light.css/dark.css, space-radius.css, typography.css), gated by WCAG 2.2 AA contrast. /theme-from-figma does the same from Figma variables.
  • Outbound: /design-export --format=design-md publishes the project's theme back out as a DESIGN.md (pure Python, no Node) — the import-into-DESIGN.md direction the upstream CLI lacks. The round-trip is semantic, not lossless: acss-kit's 18 --color-* roles map onto DESIGN.md token names (Appendix A role translation), and Material-3 ladder tokens it does not model are not reproduced.
  • The Python adapters (design_md_to_tokens.py, tokens_to_design_md.py, figma_to_tokens.py) isolate every name assumption in adapter tables; validate_design_md.py lints a file before import.
• style-agent owns the COMPONENT.md spec — the framework-neutral component half, themed by the DESIGN.md acss-kit produces. See the spec and a complete button.component.md example.

Put together: design a brand in Figma or a DESIGN.md → acss-kit turns it into a validated, themeable token set (and can hand it back out as DESIGN.md) → COMPONENT.md files describe components against those tokens → an agent projects each component into your framework of choice. Both formats are alpha/experimental and will change — pin a commit SHA when depending on them.

Why agent-driven instead of an npm package?

Most UI component libraries ship as npm packages. That model works, but it comes with trade-offs that compound over time:

• Install weight — every team member and CI runner downloads the package, its transitive dependencies, and the bundler overhead needed to tree-shake it.
• Update risk — a semver-minor bump in an upstream component library can silently change behavior, break accessibility patterns, or introduce API incompatibilities that take hours to track down.
• Ownership ceiling — once you depend on an npm package you can only customize what the package author exposed as props. Deeper changes mean forking, which puts you on the hook for rebasing security fixes forever.
• Lock-in — pinning to a specific version to stay stable means you miss bug fixes; upgrading means re-testing every consumer.

This project explores a different trade-off: components and themes live in your project as plain TSX/SCSS files generated by an agent, not as imported library code. The agent carries the reference docs, the accessibility patterns, and the OKLCH palette logic as skills. When you need a component, the agent reads the canonical spec and writes the file directly into your source tree.

The benefits of this approach:

Concern	npm package	Agent-driven
Install time	Grows with each dependency	Zero — no package to install
Customization	Limited to exposed API surface	Full source ownership — edit anything
Update breakage	A bump anywhere in the tree can break you	You control when and what changes
Bundle size	Requires tree-shaking, side-effect auditing	Only the components you actually use exist
Accessibility drift	Depends on upstream diligence	Each component is generated from a versioned, auditable spec
Onboarding	Requires understanding the library's API	The agent explains and generates — ask in plain English

The catch: this is still an evolving idea. The agent-as-package model raises real questions around reproducibility, diff-ability of generated output, and how to roll a fix across many projects at once. We're working through those — which is why the experimental warning is at the top.

Quickstart

Inside any Claude Code session running in your React + TS project — register the marketplace once, then install whichever plugin(s) you need:

/plugin marketplace add shawn-sandy/agentic-acss-plugins
/plugin install acss-kit@shawn-sandy-agentic-acss-plugins

Do this first: Run /setup once before anything else. Subsequent /kit-add and /theme-create calls depend on the .acss-target.json it writes.

Then bootstrap and add your first component + theme:

/setup                       # one-time init: sass check, ui.tsx copy, .acss-target.json, optional starter theme
/kit-add button card         # generate accessible React components into src/components/fpkit
/theme-create "#4f46e5" --mode=both   # OKLCH light + dark theme, WCAG 2.2 AA validated
/utility-add                 # optional: drop utilities.css + token-bridge.css for atomic classes

/plugin list confirms what's installed and surfaces every available slash command.

Prerequisites

• React + TypeScript project
• sass or sass-embedded in devDependencies (npm install -D sass)
• Claude Code 2.x with plugin support

Configuration

acss-kit reads .acss-target.json at your project root — created by /setup and updated by detection scripts. Top-level keys: componentsDir (where /kit-add writes generated TSX/SCSS, default src/components/fpkit), utilitiesDir (where /utility-add writes utilities.css and token-bridge.css, default src/styles), and stack (detected framework, bundler, CSS pipeline, plus entrypointFile and cssEntryFile so verify_integration.py knows where theme imports live). Generated artifacts plus this file should be committed, not gitignored. If you delete or move it, re-run /setup — pass --target=<dir> again if your original custom path differed from the default. Full schema with field semantics: plugins/acss-kit/docs/architecture.md.

Command reference

acss-kit

Setup

Command	Purpose
/setup	Bootstrap a project — package-manager detection, sass install hint, .acss-target.json, ui.tsx copy, optional starter theme.

Component generation

Command	Purpose
/kit-list [component]	List available component references or inspect one in detail (read-only).
/kit-add <component> ...	Generate accessible React components using local imports only. No @fpkit/acss package. Pass --target=html to generate static HTML + SCSS + vanilla JS instead, for non-React projects (server-rendered apps, static sites, email templates).
/kit-create <description>	Creator mode — generate a paste-ready TSX snippet (or standalone component file) from a natural-language description ("primary pill button that says 'Add to cart'"). Creator mode is handled by the kit-core skill.
/kit-sync	Bulk-install every shipped component, the ui.tsx foundation, and a starter theme in one command. Records each file in .acss-kit/manifest.json for safe re-syncs.
/kit-update [<component> ...]	Safely re-copy unmodified generated files after a plugin upgrade. Drift detection via normalized sha256 — files you've edited are skipped by default.

Themes

Command	Purpose
/theme-create <hex> [--mode=light|dark|both]	Generate semantic CSS theme files from a seed color and validate required WCAG contrast pairs.
/theme-brand <name> [--from=<hex>]	Scaffold a brand-<name>.css preset that layers over light/dark.
/theme-update <file> <--color-role=#hex> ...	Edit role values in an existing theme file and re-validate contrast.
/theme-extract <image|figma-url>	Pull a primary brand color from a design input and run the theme generation flow.
/theme-from-design <DESIGN.md>	Generate a full theme (colors + spacing + rounded + typography) from a Google DESIGN.md. Requires Node/npx.
/theme-from-figma <figma-url>	Generate a theme from a Figma file's variables via the Figma MCP server. Pure Python after the MCP call.
/design-export [--format=design-md|dtcg|tailwind]	Publish the project's theme as a DESIGN.md (default, pure Python) or DTCG/Tailwind (npx). The outbound half of the DESIGN.md bridge.
/color-scale <color> [--name=<name>] [--format=css|json|both]	Generate a 10-step OKLCH color scale (steps 50–900) from any hex, CSS named color, or theme role.

Tuning

Command	Purpose
/style-tune <description>	Natural-language tuning of theme roles or component tokens ("warmer button", "deeper accent for primary").

Help

Command	Purpose
/prompt-book [section-number]	Print a copy-paste catalogue of natural-language prompts for every shipped slash command.

Utility classes

Command	Purpose
/utility-add	Copy utilities.css (and token-bridge.css) into a target project. Family filtering supported.
/utility-list [family]	List utility families and their classes.
/utility-bridge	Regenerate token-bridge.css against the active acss-kit theme.
/utility-tune <description>	Adjust utilities.tokens.json from natural language and regenerate.

Skills (22 total — 15 per-component + 7 named):

• 15 component-<name> skills (component-alert … component-table) — each ships a SKILL.md workflow plus a reference.md with markdown-as-source TSX/SCSS templates and embedded accessibility patterns.
• kit-core — orchestrator behind /kit-create, /kit-list, /kit-sync, /kit-update, and the Form/HTML/Style-Tune modes; holds the shared references (architecture, accessibility, css-variables, composition, foundation).
• styles — OKLCH theme generation, role catalogue, palette algorithm, brand presets, WCAG 2.2 AA validation.
• utilities — atomic-CSS bundle management (utilities.css, token-bridge.css).
• setup — cross-domain init skill backing /setup.
• style-tune — feel-tuning skill backing /style-tune.
• kit-sync — bulk-install skill backing /kit-sync.
• prompt-book — prompt-catalogue skill backing /prompt-book.

Repository layout

agentic-acss-plugins/
├── .claude-plugin/marketplace.json   # marketplace manifest
├── plugins/
│   ├── acss-kit/
│   │   ├── .claude-plugin/plugin.json     # version source of truth
│   │   ├── commands/*.md                  # slash commands
│   │   ├── skills/component-<name>/          # 15 per-component skills (SKILL.md + reference.md)
│   │   ├── skills/{kit-core,styles,utilities,setup,style-tune,kit-sync,prompt-book}/SKILL.md
│   │   ├── scripts/                       # Python 3 stdlib (palette, validate, detect_target, …)
│   │   ├── assets/                        # ui.tsx foundation, brand template, theme schema, utilities bundle
│   │   └── docs/                          # architecture, recipes, troubleshooting, tutorial
│   └── style-agent/
│       ├── .claude-plugin/plugin.json
│       ├── commands/*.md                  # /css-to-class, /inline-style-to-class, /create-utilities
│       └── skills/                        # framework-agnostic CSS authoring skills
├── tests/                              # tests/run.sh structural validation, tests/e2e.sh deeper check
├── docs/                               # cross-plugin documentation
├── .claude/                            # maintainer-only — project rules, hooks, skills, and review agents for plugin development; not surfaced to plugin users
├── CLAUDE.md                           # repo guidance for Claude Code
├── AGENTS.md                           # agent definitions
└── CONTRIBUTING.md                     # contributor workflow

Migration

If you previously installed acss-kit-builder, acss-theme-builder, acss-app-builder, or acss-component-specs — these have been consolidated into acss-kit (or removed entirely). Uninstall the old plugins and install acss-kit instead. See plugins/acss-kit/CHANGELOG.md for the full history.

Existing .acss-target.json files at project roots remain compatible — the schema is unchanged.

Testing locally

tests/run.sh is the default automated check — structural validation in ~30 seconds, no browser. One-time setup: npm --prefix tests ci && pip3 install --user tinycss2.

tests/run.sh

For render-sensitive changes, tests/e2e.sh runs the deeper opt-in check — extracts components from reference docs, type-checks them with tsc --noEmit, compiles SCSS, validates theme contrast, and runs jsdom + axe-core a11y on rendered output.

For end-to-end slash-command verification, tests/setup.sh writes a minimal verification fixture at tests/sandbox/ (gitignored):

tests/setup.sh
cd tests/sandbox && claude

To test a local plugin install without publishing:

claude --plugin-dir ./plugins/acss-kit

See tests/README.md for the full workflow, the --reset flag, escape hatches, and troubleshooting.

Documentation map

Doc	Audience	Covers
CONTRIBUTING.md	Contributors	Branching model, fpkit sibling-clone workflow, review process
CLAUDE.md	Claude Code sessions	Repo-level guidance — plugin layout, version-bump rules, pre-submit checklist
AGENTS.md	Maintainers	Project agent definitions
plugins/acss-kit/README.md	acss-kit users	Full plugin behavior, command catalog, skills overview
plugins/acss-kit/docs/	acss-kit contributors	Architecture, recipes, troubleshooting, tutorial
plugins/style-agent/README.md	style-agent users	CSS authoring commands, the COMPONENT.md spec
plugins/style-agent/docs/component-md/spec.md	Design-system authors	COMPONENT.md format — front-matter, neutral body, target adapters, DESIGN.md coupling
tests/README.md	All	Local test workflow, sandbox fixtures, reset/troubleshooting

Relationship to the main fpkit repo

Plugin development references the live fpkit source at shawn-sandy/acss. SKILL.md files and reference docs link to specific fpkit source files via full GitHub URLs, so plugin users can click through without a local clone. Contributors should keep both repos available side-by-side — see CONTRIBUTING.md for the workflow.

License

MIT — see LICENSE.