convez.ai
AgenteDesenvolvimento WebIntermediário
shawn-sandy

ACSS Plugins - Marketplace de Componentes React Acessíveis

shawn-sandy/agentic-acss-plugins

Componentes React acessíveis e temas OKLCH gerados por agentes, sem npm

Ver no GitHub
BomPluginScore · de 0 a 100

Marketplace de plugins Claude Code para construir aplicações React acessíveis com o sistema de design fpkit/acss. Dois plugins desacoplados (acss-kit e style-agent) que geram componentes TSX, temas OKLCH e utilitários CSS direto no seu projeto, sem dependências npm. Substitui pacotes npm por skills orientadas por agentes.

Instalação

$npx convez-ai shawn-sandy/agentic-acss-plugins

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 4 meses
Versão
—
Issues abertas
2
Contribuidores
3

Casos de uso

  • Gerar componentes React acessíveis (WCAG 2.2 AA) sob demanda
  • Criar temas tokenizados em OKLCH sem adicionar dependências ao projeto
  • Converter estilos inline ou plain-language em classes utilitárias nomeadas
  • Manter controle total sobre código gerado sem lock-in de bibliotecas

Veredito

Abordagem experimental e intrigante que questiona o modelo npm tradicional. Útil para equipes React/TypeScript que buscam acessibilidade rigorosa e propriedade total do código gerado, mas ainda em validação — APIs podem mudar. Melhor para projetos que conseguem absorver variações de API em troca de maior controle.

README

A tradução para o português deste README ainda está na fila.

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

PluginVersionWhat it ships
acss-kit1.8.0Accessible 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-agent0.5.0Framework-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.

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:

Concernnpm packageAgent-driven
Install timeGrows with each dependencyZero — no package to install
CustomizationLimited to exposed API surfaceFull source ownership — edit anything
Update breakageA bump anywhere in the tree can break youYou control when and what changes
Bundle sizeRequires tree-shaking, side-effect auditingOnly the components you actually use exist
Accessibility driftDepends on upstream diligenceEach component is generated from a versioned, auditable spec
OnboardingRequires understanding the library's APIThe 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

CommandPurpose
/setupBootstrap a project — package-manager detection, sass install hint, .acss-target.json, ui.tsx copy, optional starter theme.

Component generation

CommandPurpose
/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-syncBulk-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

CommandPurpose
/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

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

Help

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

Utility classes

CommandPurpose
/utility-addCopy utilities.css (and token-bridge.css) into a target project. Family filtering supported.
/utility-list [family]List utility families and their classes.
/utility-bridgeRegenerate 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

DocAudienceCovers
CONTRIBUTING.mdContributorsBranching model, fpkit sibling-clone workflow, review process
CLAUDE.mdClaude Code sessionsRepo-level guidance — plugin layout, version-bump rules, pre-submit checklist
AGENTS.mdMaintainersProject agent definitions
plugins/acss-kit/README.mdacss-kit usersFull plugin behavior, command catalog, skills overview
plugins/acss-kit/docs/acss-kit contributorsArchitecture, recipes, troubleshooting, tutorial
tests/README.mdAllLocal 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.

Ver o original no GitHub

Bom para

Relacionados