shawn-sandy/acss-app-builder

acss-app-builder

A single-skill workflow for scaffolding apps with the @fpkit/acss design system. Each slash command corresponds to one section below.

---

Shared preflight (every command EXCEPT /app-init)

1. Detect Vite+React — run scripts/detect_vite_project.py. Halt if not detected.
2. Detect component source — run scripts/detect_component_source.py. Returns generated | npm | none. Generated wins on tie. On none, halt with install hints.
3. Check theme base — if src/styles/theme/base.css is missing, prompt the developer to run /app-theme light first.

Safety contract — applied to every command:

• If git status --porcelain is non-empty, halt unless --force.
• If any target file already exists with non-empty content, halt and list conflicts unless --force.
• src/main.tsx mutation uses sentinel-bounded blocks (// @acss-app-builder:begin ... :end). Re-runs update in place.

---

/app-init [--with=theme,layout] [--force]

Purpose: Bootstrap project folders and wire theme imports into the entry file.

Preflight exemption: skips step 3 of the shared preflight (it creates base.css).

Workflow

1. Verify Vite+React via detect_vite_project.py. Read the entry file path from its output (usually src/main.tsx).
2. Verify sass or sass-embedded is in devDependencies. If missing, print npm install -D sass and halt.
3. Create the folder structure:

   src/app/
   src/pages/
   src/styles/theme/
   

   Refuse if any exists with non-empty content (unless --force).
4. Copy assets/themes/base.css → src/styles/theme/base.css.
5. Determine the components target directory. If .acss-target.json exists at project root, read componentsDir from it. Else prompt (default src/components/fpkit) and write .acss-target.json.
6. Locate the last ^import .* from ['"].*['"];?$ line in the entry file. Append the sentinel block after it:

   // @acss-app-builder:begin theme imports
   import './styles/theme/base.css'
   // @acss-app-builder:end
   

   If no imports exist, halt with instructions.
7. If --with=theme, run /app-theme light workflow inline. If --with=layout, run /app-layout sidebar inline.
8. Print a summary: created folders, entry-file mutation, next-step hints (/app-page dashboard, /kit-add button).

References to load

• references/app-architecture.md — entry mutation contract, project-root definition.
• references/component-source.md — import-map semantics for later commands.

---

/app-layout <holy-grail|sidebar|centered> [--force]

Purpose: Generate src/app/AppShell.tsx + src/app/AppShell.scss with grid-area CSS variables.

Workflow

1. Run shared preflight.
2. Read assets/layouts/app-shell-<shell>.tsx.
3. Resolve {{IMPORT_SOURCE:...}} tokens via detect_component_source.py.
4. Compute relative paths from src/app/AppShell.tsx depth (../components/fpkit/... for generated).
5. Write src/app/AppShell.tsx + src/app/AppShell.scss. Refuse on existing non-empty content without --force.
6. Print import snippet for use in src/App.tsx.

References

• references/layouts.md — shell catalog, grid areas, responsive rules.
• references/component-source.md.

---

/app-page <template> [name] [--force]

Templates: dashboard, auth-login, auth-signup, settings, list-detail, landing, error-404, error-500.

Workflow

1. Run shared preflight.
2. If name omitted, derive PascalCase from template (e.g. auth-login → AuthLogin).
3. Read assets/pages/<template>.tsx. If template file uses specific fpkit components, verify each against the active source:
   • For generated: check <componentsDir>/<component>/<component>.tsx exists. If missing, print /kit-add <component> hint and halt.
   • For npm: assume the package exports from packages/fpkit/src/index.ts.
4. Substitute {{IMPORT_SOURCE:...}}, {{NAME}}, {{ROUTE}} tokens.
5. Write to src/pages/<Name>.tsx (refuse without --force on conflict).
6. Print wiring snippet for src/App.tsx or the developer's router.

References

• references/pages.md — catalog, accessibility requirements, tab-pattern clarification.
• references/layouts.md — for shell composition.
• references/patterns.md — patterns a page template may include.
• references/composition.md — when the page requires composing multiple fpkit primitives.

---

/app-theme <light|dark|both|brand-neutral|brand-vibrant> [--mode=light|dark|both]

Workflow

1. Run shared preflight (the theme-base check passes if this is /app-theme light or both because the command is about to create it — exempt this command from step 3 of preflight).
2. For the selected preset(s), copy the corresponding assets/themes/*.css to src/styles/theme/.
3. Append a sentinel-bounded CSS import block to the entry file for each newly-written theme (update existing block if present).
4. Run scripts/validate_theme.py src/styles/theme/. Report WCAG contrast failures as warnings; the command continues unless the developer passes --strict-contrast.

Note: scripts/validate_css_vars.py is NOT run on theme files. That validator enforces the --{component}-{property} pattern, which is correct for component SCSS (--btn-bg) but a category mismatch for primitive design tokens (--fs-xs, --space-1) and semantic role tokens (--color-primary). Use validate_css_vars.py only on files under src/components/ (invoked by /app-compose and by developers directly).

References

• references/themes.md.
• references/css-variables.md.

---

/app-form <schema.json> [--name=FormName] [--force]

Workflow

1. Run shared preflight.
2. Read the schema file. Validate required keys (name, fields). Each field must have name, label, type.
3. Resolve --name or fall back to schema.name.
4. Read assets/forms/form-from-schema.tsx.tmpl and assets/forms/field-renderers.tsx.
5. For each field, pick the renderer per the type→renderer mapping (see references/forms.md). Generate unique ids (<FormName>-<fieldName>).
6. Substitute {{IMPORT_SOURCE:Field,Input,Checkbox,Button}} and the rendered field list.
7. Write to src/forms/<FormName>.tsx. Refuse without --force on conflict.
8. Print a usage snippet for the developer.

References

• references/forms.md — verified Field API, schema shape.
• references/accessibility.md.
• references/composition.md.

---

/app-pattern <pattern> [--into=<file>] [--force]

Patterns: data-table, empty-state, loading-skeleton, hero, pricing-grid, notification-toast.

Workflow

1. Run shared preflight.
2. Read assets/patterns/<pattern>.tsx.
3. If --into absent: write to src/patterns/<Name>.tsx (PascalCase from pattern name).
4. If --into present: a. Read the target file. b. Find the first {/* @acss-app-builder:insert */} marker. If absent, print the exact comment to add and halt. c. Substitute imports (merge with existing imports in the target file; dedupe). d. Replace the marker with the pattern's JSX body. e. Write the modified file.
5. If the pattern has a .scss, write it alongside the .tsx or ensure it's imported into the target file.

References

• references/patterns.md.
• references/component-source.md.

---

/app-compose <name> [description]

Migrated from the deprecated fpkit-developer plugin. Guides composition and extension of fpkit components.

Workflow

1. Run shared preflight.
2. Analyze — read the developer's description. Ask clarifying questions if ambiguous.
3. Check catalog — is there already an fpkit export that fits? If yes, propose using it directly with CSS variable customization. Skip to step 6.
4. Decide compose vs extend vs custom using this tree:
   • Can it be built by composing 2+ fpkit primitives? → compose (step 5a).
   • Can an existing fpkit component be wrapped with added behavior? → extend (step 5b).
   • Otherwise → custom (step 5c).
5. Generate the component: a. Compose — write src/components/<Name>.tsx importing multiple fpkit primitives; extend their prop types with TypeScript; spread ...props. Keep depth ≤ 3. b. Extend — wrap one fpkit primitive, extend its prop type (not replace), preserve aria-disabled + focus behavior. c. Custom — use semantic HTML, rem units, CSS variables following the naming standard. Run scripts/validate_css_vars.py before finishing.
6. Accessibility gate — verify:
   • semantic HTML (<button>, not <div role="button">),
   • keyboard reachability,
   • visible focus,
   • labels/ARIA where needed,
   • WCAG AA contrast on any custom colors.
7. Print the finished component and a sample test using vitest-axe (NOT jest-axe — Vitest environment).

References

• references/composition.md — decision tree, 5 compose patterns, anti-patterns.
• references/accessibility.md — WCAG AA requirements.
• references/architecture.md — polymorphic UI, as prop.
• references/testing.md — Vitest + RTL patterns.

---

Key rules across all commands

1. No @/ import aliases — use relative imports.
2. Generated source wins on tie — if <componentsDir>/ui.tsx exists, never import from @fpkit/acss.
3. Never invent exports — the authoritative list is packages/fpkit/src/index.ts. Do not import FieldLabel, FieldInput, Select, or Textarea as named exports (they are not there).
4. Refuse, don't overwrite — require --force for any non-empty target.
5. Refuse on dirty tree — require committed or stashed changes before mutating the project.
6. Sentinel blocks for entry mutation — never use regex rewriting on src/main.tsx.
7. .acss-target.json is committed — both plugins read and write it; it is the single source of truth for the components directory.