Add cross-tool workflow: AGENTS.md, Antigravity workflows, documentation
- Create AGENTS.md (90 lines) as shared foundation for Claude Code + Antigravity - Slim CLAUDE.md from 113 to 45 lines (Claude-specific only, references AGENTS.md) - Slim GEMINI.md from 58 to 26 lines (Antigravity-specific only, references AGENTS.md) - Add 6 Antigravity workflows in .agent/workflows/ (session-start, preflight, token-sync, visual-qa, build-component, page-review) - Add docs/reference/cross-tool-workflow.md with task routing, quality gates, file ownership, error mitigation - Zero content overlap between CLAUDE.md and GEMINI.md (was ~80%) - File ownership boundaries defined for current phase and future backend work Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
51
.agent/workflows/fa-build-component.md
Normal file
51
.agent/workflows/fa-build-component.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
description: Scaffold and build a new component following FA conventions and the full component lifecycle.
|
||||
---
|
||||
|
||||
# Build Component
|
||||
|
||||
Create a new component following the FA design system conventions and the
|
||||
component lifecycle defined in `docs/reference/component-lifecycle.md`.
|
||||
|
||||
## Arguments
|
||||
|
||||
Provide the tier and component name (e.g., `atom Button`, `molecule PriceCard`).
|
||||
|
||||
## Pre-flight
|
||||
|
||||
1. Read `docs/memory/component-registry.md` — confirm component is planned, not already in-progress
|
||||
2. **Dependency check (molecules):** all constituent atoms must be `done`
|
||||
3. **Dependency check (organisms):** all constituent molecules and atoms must be `done`
|
||||
4. Read `docs/conventions/component-conventions.md` — follow the template
|
||||
5. Read `docs/design-system.md` — understand brand context for this component
|
||||
6. Read `docs/memory/token-registry.md` — know available tokens
|
||||
|
||||
If any dependency is not met, STOP and report what's missing.
|
||||
|
||||
## Build
|
||||
|
||||
1. Create folder: `src/components/{tier}/{ComponentName}/`
|
||||
2. Create `ComponentName.tsx`:
|
||||
- Extend appropriate MUI base component props
|
||||
- All visual values from theme (never hardcode)
|
||||
- `React.forwardRef` for interactive elements
|
||||
- Forward `sx` prop
|
||||
- JSDoc on every prop
|
||||
- `displayName` set
|
||||
3. Create `ComponentName.stories.tsx`:
|
||||
- `tags: ['autodocs']` in meta
|
||||
- Stories: Default, AllVariants, AllSizes, Disabled, Loading, Error, LongContent, MinimalContent
|
||||
4. Create `index.ts` barrel export
|
||||
5. Create component tokens in `tokens/component/{component}.json` if needed
|
||||
|
||||
## Verify
|
||||
|
||||
- Open story in Storybook at `localhost:6006`
|
||||
- Confirm all stories render without errors
|
||||
- Check visual appearance matches design system
|
||||
|
||||
## After
|
||||
|
||||
- Update `docs/memory/component-registry.md` — mark as `review`
|
||||
- Update `docs/memory/token-registry.md` if tokens were created
|
||||
- Update `docs/memory/decisions-log.md` with any design decisions
|
||||
91
.agent/workflows/fa-page-review.md
Normal file
91
.agent/workflows/fa-page-review.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
description: Review and tweak an existing page — visual QA, spacing adjustments, copy refinement, responsive check. Current phase focus.
|
||||
---
|
||||
|
||||
# Page Review
|
||||
|
||||
Review an existing page component for visual quality, consistency, and polish.
|
||||
This is the primary workflow for the current project phase (tweaking and
|
||||
finalising pages rather than building from scratch).
|
||||
|
||||
## Arguments
|
||||
|
||||
Provide the page name (e.g., `ProvidersStep`, `HomePage`, `CoffinsStep`).
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Gather context
|
||||
|
||||
- Read the page source: `src/components/pages/{PageName}/{PageName}.tsx`
|
||||
- Read its stories: `src/components/pages/{PageName}/{PageName}.stories.tsx`
|
||||
- Check `docs/memory/session-log.md` for recent changes to this page
|
||||
- Check `docs/memory/decisions-log.md` for relevant design decisions
|
||||
|
||||
### 2. Open in Storybook
|
||||
|
||||
Navigate to `localhost:6006` and open the page's default story.
|
||||
|
||||
### 3. Review checklist
|
||||
|
||||
At each breakpoint (375px mobile, 768px tablet, 1280px desktop):
|
||||
|
||||
**Visual hierarchy**
|
||||
- Heading sizes follow a clear progression (display → h1 → h2 → body)
|
||||
- Primary action is visually prominent
|
||||
- Whitespace groups related content, separates unrelated
|
||||
|
||||
**Spacing**
|
||||
- All spacing uses `theme.spacing()` — no magic numbers
|
||||
- Consistent gaps between sections (typically spacing(4) or spacing(6))
|
||||
- No visual crowding; no excessive empty space
|
||||
|
||||
**Typography**
|
||||
- Body text line length between 45-75 characters
|
||||
- Line heights readable (1.5 for body, tighter for headings)
|
||||
- Font weights create clear distinction between labels and content
|
||||
|
||||
**Colour**
|
||||
- All colours from theme/tokens — no raw hex in source
|
||||
- Contrast meets WCAG AA (4.5:1 normal text, 3:1 large text)
|
||||
- Error states use copper (#B0610F), not red
|
||||
|
||||
**Responsive**
|
||||
- Content reflows cleanly between breakpoints
|
||||
- No horizontal overflow or content clipping
|
||||
- Touch targets at least 44px on mobile
|
||||
- Images and cards scale proportionally
|
||||
|
||||
**Copy**
|
||||
- Warm but not gushy — understated empathy
|
||||
- Labels are clear, unambiguous, sentence case
|
||||
- CTAs use action verbs ("Continue", "Select", "Save")
|
||||
- No jargon or funeral-industry terms without context
|
||||
|
||||
**Interactive states**
|
||||
- Hover, focus, disabled visible on all controls
|
||||
- Focus indicators: 2px solid, 2px offset, visible on `:focus-visible`
|
||||
- Disabled: reduced opacity, no pointer events
|
||||
|
||||
**Edge cases**
|
||||
- Long content handled (truncation, scroll, or wrap)
|
||||
- Empty/minimal content doesn't break layout
|
||||
- Loading states present where data is async
|
||||
|
||||
### 4. Make targeted fixes
|
||||
|
||||
For issues found:
|
||||
- Make small, focused changes (spacing, copy, alignment)
|
||||
- Do NOT restructure the page — this is polish, not redesign
|
||||
- Reference design decisions from decisions-log.md when relevant
|
||||
|
||||
### 5. Before/after comparison
|
||||
|
||||
- Screenshot the page at each breakpoint BEFORE and AFTER changes
|
||||
- Present both to the user for approval
|
||||
|
||||
### 6. Report
|
||||
|
||||
Summarise:
|
||||
- Changes made (with file and line references)
|
||||
- Remaining issues (with severity P0/P1/P2)
|
||||
- Suggested next steps (e.g., "run fa-preflight before committing")
|
||||
52
.agent/workflows/fa-preflight.md
Normal file
52
.agent/workflows/fa-preflight.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
description: Pre-commit quality checks — TypeScript, ESLint, Prettier, Storybook build, token sync, hardcoded values. // turbo
|
||||
---
|
||||
|
||||
# Preflight Checks
|
||||
|
||||
Run all quality gates before committing. Report PASS/FAIL/WARN for each.
|
||||
|
||||
## Checks
|
||||
|
||||
1. **TypeScript compilation**
|
||||
Run `npx tsc --noEmit`
|
||||
FAIL if any type errors. Report file and line for each error.
|
||||
|
||||
2. **ESLint**
|
||||
Run `npm run lint`
|
||||
FAIL if any errors (warnings are WARN). Report count and top issues.
|
||||
|
||||
3. **Prettier**
|
||||
Run `npm run format:check`
|
||||
FAIL if any files need formatting. List files.
|
||||
|
||||
4. **Storybook build**
|
||||
Run `npx storybook build --quiet`
|
||||
FAIL if build errors. Report the failing component.
|
||||
|
||||
5. **Token sync**
|
||||
Compare timestamps: are any `tokens/**/*.json` files newer than `src/theme/generated/`?
|
||||
WARN if generated files are stale. Fix: `npm run build:tokens`
|
||||
|
||||
6. **Hardcoded values scan**
|
||||
Search `src/components/**/*.tsx` (excluding `*.stories.tsx`) for hex colour patterns (`#[0-9a-fA-F]{3,8}`).
|
||||
WARN for each match not on a line containing `// ok-hardcode`.
|
||||
|
||||
7. **Component exports**
|
||||
For each component folder in `src/components/`, verify `index.ts` exists and re-exports the component.
|
||||
FAIL if any component is missing its barrel export.
|
||||
|
||||
## Report format
|
||||
|
||||
| Check | Status | Details |
|
||||
|-------|--------|---------|
|
||||
| TypeScript | PASS/FAIL | error count |
|
||||
| ESLint | PASS/FAIL/WARN | error/warning count |
|
||||
| Prettier | PASS/FAIL | files needing format |
|
||||
| Storybook | PASS/FAIL | failing component |
|
||||
| Token sync | PASS/WARN | stale files |
|
||||
| Hardcoded values | PASS/WARN | matches found |
|
||||
| Exports | PASS/FAIL | missing index.ts |
|
||||
|
||||
If all PASS: safe to commit.
|
||||
If any FAIL: fix before committing.
|
||||
37
.agent/workflows/fa-session-start.md
Normal file
37
.agent/workflows/fa-session-start.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: Start a work session — read memory files, check project status, report what needs attention.
|
||||
---
|
||||
|
||||
# Session Start
|
||||
|
||||
Read project state and report a summary before beginning work.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Read recent activity**
|
||||
- Read `docs/memory/session-log.md` — summarise the last 2-3 sessions
|
||||
- Note any incomplete work or open questions
|
||||
|
||||
2. **Check component status**
|
||||
- Read `docs/memory/component-registry.md`
|
||||
- Count components by status: done, in-progress, planned, needs-revision
|
||||
- Flag any components stuck in "in-progress" or "needs-revision"
|
||||
|
||||
3. **Check token status**
|
||||
- Read `docs/memory/token-registry.md`
|
||||
- Note any gaps or recently added tokens
|
||||
|
||||
4. **Check pending reviews**
|
||||
- Read `docs/reference/retroactive-review-plan.md`
|
||||
- List any tiers or components that haven't been reviewed yet
|
||||
|
||||
5. **Check recent decisions**
|
||||
- Read `docs/memory/decisions-log.md`
|
||||
- Note the 3 most recent decisions and their status
|
||||
|
||||
6. **Report**
|
||||
Present a brief summary:
|
||||
- Recent activity (1-2 sentences)
|
||||
- Component stats (done/in-progress/planned)
|
||||
- Pending review items
|
||||
- Suggested next actions
|
||||
28
.agent/workflows/fa-token-sync.md
Normal file
28
.agent/workflows/fa-token-sync.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
description: Rebuild CSS and JS outputs from token JSON sources. // turbo
|
||||
---
|
||||
|
||||
# Token Sync
|
||||
|
||||
Validate token JSON and regenerate all outputs.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Validate token files**
|
||||
Read each file in `tokens/primitives/`, `tokens/semantic/`, `tokens/component/`.
|
||||
Every token object must have `$value`, `$type`, and `$description`.
|
||||
Report any tokens missing required fields.
|
||||
|
||||
2. **Build tokens**
|
||||
Run `npm run build:tokens`
|
||||
Report success or failure with error details.
|
||||
|
||||
3. **Verify outputs**
|
||||
Confirm these generated files exist and are non-empty:
|
||||
- `src/theme/generated/tokens.css`
|
||||
- `src/theme/generated/tokens.js`
|
||||
Report any missing or empty outputs.
|
||||
|
||||
4. **Check theme integration**
|
||||
Read `src/theme/index.ts` — are any newly added tokens missing from the MUI theme mapping?
|
||||
Report tokens that exist in generated output but aren't consumed by the theme.
|
||||
40
.agent/workflows/fa-visual-qa.md
Normal file
40
.agent/workflows/fa-visual-qa.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
description: Browser-based visual QA of a component or page in Storybook. Checks spacing, alignment, states, responsive behaviour.
|
||||
---
|
||||
|
||||
# Visual QA
|
||||
|
||||
Open a component or page story in Storybook and perform a visual quality check
|
||||
at multiple breakpoints.
|
||||
|
||||
## Arguments
|
||||
|
||||
Provide the component name or story path (e.g., `ProvidersStep`, `Button`, `Pages/HomePage`).
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Ensure Storybook is running** at `localhost:6006`
|
||||
|
||||
2. **Navigate to the story**
|
||||
Construct URL: `http://localhost:6006/?path=/story/{tier}-{componentname}--default`
|
||||
If the component is a page: `pages-{pagename}--default`
|
||||
|
||||
3. **Check at three breakpoints**
|
||||
For each of mobile (375px), tablet (768px), desktop (1280px):
|
||||
|
||||
- **Spacing:** consistent use of the spacing scale, no visual crowding or excessive gaps
|
||||
- **Alignment:** elements aligned to grid, no off-by-one shifts
|
||||
- **Typography:** hierarchy readable, line lengths between 45-75 characters, weights distinct
|
||||
- **Colour:** all values appear to come from the design system (warm golds, neutral greys, copper accents)
|
||||
- **Interactive states** (if applicable): hover, focus, disabled look correct
|
||||
- **Overflow:** no content clipping, horizontal scroll, or text truncation issues
|
||||
- **Touch targets:** buttons and interactive elements appear at least 44px at mobile
|
||||
|
||||
4. **Screenshot each breakpoint**
|
||||
Capture and present to user for review.
|
||||
|
||||
5. **Report findings**
|
||||
List issues found with severity:
|
||||
- **P0:** Broken layout, missing content, inaccessible controls
|
||||
- **P1:** Spacing inconsistency, contrast failure, overflow at one breakpoint
|
||||
- **P2:** Minor alignment, typography weight, polish items
|
||||
90
AGENTS.md
Normal file
90
AGENTS.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# FA 2.0 Design System
|
||||
|
||||
## Project
|
||||
|
||||
Funeral Arranger (funeralarranger.com.au) design system rebuild. Client: Parsons
|
||||
(H.Parsons Funeral Directors). Users are often in distress — the design language
|
||||
must be warm, professional, trustworthy, and calm.
|
||||
|
||||
## Tech stack
|
||||
|
||||
- React 18 + TypeScript
|
||||
- Material UI (MUI) v5
|
||||
- Storybook 8+ with autodocs
|
||||
- Style Dictionary for token transformation
|
||||
- W3C DTCG token format (2025.10 stable spec)
|
||||
|
||||
## Architecture
|
||||
|
||||
Source of truth: token JSON files in `tokens/` (DTCG format).
|
||||
Flow: Token JSON → Style Dictionary → MUI theme + CSS vars → React components → Storybook
|
||||
|
||||
Token tiers: primitives (`tokens/primitives/`) → semantic (`tokens/semantic/`) → component (`tokens/component/`)
|
||||
Component tiers: atoms → molecules → organisms → templates → pages (in `src/components/`)
|
||||
|
||||
## Commands
|
||||
|
||||
- `npm run build:tokens` — regenerate CSS/JS from token JSON (run after any token change)
|
||||
- `npm run storybook` — dev server on localhost:6006
|
||||
- `npm run type-check` — TypeScript compilation check
|
||||
- `npm run lint` / `npm run lint:fix` — ESLint
|
||||
- `npm run format` / `npm run format:check` — Prettier
|
||||
- `npm run test` — Vitest
|
||||
|
||||
## Rules (always)
|
||||
|
||||
1. Consume the MUI theme for all visual values — `theme.palette.*`, `theme.spacing()`, `theme.typography.*`
|
||||
2. Every token has `$value`, `$type`, and `$description` (DTCG format)
|
||||
3. Error styling uses copper (#B0610F) not red — grief-sensitive context
|
||||
4. Read `docs/memory/` before starting work (decisions-log, component-registry, token-registry, session-log)
|
||||
5. Update `docs/memory/` after completing work
|
||||
6. Run `npm run build:tokens` after any token JSON change
|
||||
7. Verify in Storybook before marking any component done
|
||||
8. Follow the component lifecycle in `docs/reference/component-lifecycle.md`
|
||||
9. Commit and push after each coherent unit of work
|
||||
|
||||
## Rules (never)
|
||||
|
||||
- Use raw hex values in component source files — map to semantic tokens
|
||||
- Mix token access methods — semantic via `theme.*`, component via `var(--fa-*)`
|
||||
- Skip the barrel export (`index.ts`) for any component
|
||||
- Edit files owned by another agent without coordinating (see File ownership)
|
||||
|
||||
## Git workflow
|
||||
|
||||
Remote: Gitea at `http://192.168.50.211:3000/richie/ParsonsFA.git`
|
||||
Branch: all work on `main` for now.
|
||||
|
||||
Stage specific files (not `git add -A`). Commit message format:
|
||||
```
|
||||
Short summary (imperative mood, <70 chars)
|
||||
|
||||
- Bullet points with detail if needed
|
||||
- Reference decision IDs (D001, D002...) when relevant
|
||||
```
|
||||
|
||||
## File conventions
|
||||
|
||||
- Component folders: PascalCase — `Button/`, `PriceCard/`
|
||||
- Token files: camelCase — `colours.json`, `typography.json`
|
||||
- Each component folder: `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
|
||||
- CSS custom properties prefix: `--fa-`
|
||||
- Semantic tokens via theme, component tokens via CSS vars — see `docs/conventions/token-conventions.md`
|
||||
- Component structure and props: see `docs/conventions/component-conventions.md`
|
||||
|
||||
## Key references
|
||||
|
||||
- Design spec: `docs/design-system.md`
|
||||
- Component lifecycle: `docs/reference/component-lifecycle.md`
|
||||
- Flow architecture (wizard steps, branching, fields): `documentation/flow-definition.yaml`
|
||||
- Redesigned flow spec: `documentation/steps/flow-definition.yaml` + `documentation/steps/flow-spec.md`
|
||||
- Cross-tool workflow: `docs/reference/cross-tool-workflow.md`
|
||||
|
||||
## File ownership
|
||||
|
||||
One file, one owner at a time. Check `docs/memory/session-log.md` before starting.
|
||||
|
||||
- **Component source, tokens, theme, memory files:** Claude Code owns writes
|
||||
- **Visual QA, browser verification, screenshots:** Antigravity owns
|
||||
- **Shared read:** all documentation, all source files, AGENTS.md
|
||||
- **When backend agent starts:** backend owns `src/payload/`, `src/api/`; frontend agents never touch those. `documentation/flow-definition.yaml` is the shared contract.
|
||||
124
CLAUDE.md
124
CLAUDE.md
@@ -1,113 +1,45 @@
|
||||
# FA 2.0 Design System
|
||||
# Claude Code — FA 2.0 Design System
|
||||
|
||||
## Project overview
|
||||
Follow all rules in `AGENTS.md`. This file contains Claude-specific behaviour only.
|
||||
|
||||
Rebuilding the Funeral Arranger (funeralarranger.com.au) design system using a
|
||||
code-first approach. Parsons (H.Parsons Funeral Directors) is the client. FA is
|
||||
an Australian funeral planning platform — the design language must be warm,
|
||||
professional, trustworthy, and calm. Users are often in distress.
|
||||
## Session startup (automatic)
|
||||
|
||||
## Tech stack
|
||||
At the start of every session, automatically:
|
||||
1. Read `docs/memory/session-log.md`, `decisions-log.md`, `component-registry.md`
|
||||
2. Check `docs/reference/retroactive-review-plan.md` for pending review tiers
|
||||
3. If reviews remain, run the next step (~30-60 min) before the user's main request
|
||||
4. Report findings, then shift to whatever the user wants to work on
|
||||
|
||||
- React 18 + TypeScript
|
||||
- Material UI (MUI) v5
|
||||
- Storybook 8+ with autodocs
|
||||
- Style Dictionary for token transformation
|
||||
- W3C DTCG token format (2025.10 stable spec)
|
||||
- Chromatic for Storybook hosting (later)
|
||||
|
||||
## Architecture
|
||||
|
||||
**Source of truth:** Token JSON files in `tokens/` (DTCG format)
|
||||
**Flow:** Token JSON → Style Dictionary → MUI theme + CSS vars → React components → Storybook
|
||||
|
||||
### Token tiers
|
||||
1. **Primitives** (`tokens/primitives/`): Raw values — hex, px, font names, scales
|
||||
2. **Semantic** (`tokens/semantic/`): Design intent — `color.text.primary`, `color.surface.default`
|
||||
3. **Component** (`tokens/component/`): Per-component — `button.background.default`
|
||||
|
||||
### Component tiers (atomic design)
|
||||
1. **Atoms** (`src/components/atoms/`): Button, Input, Typography, Badge, Icon, Avatar, Divider, Chip, Card, Link
|
||||
2. **Molecules** (`src/components/molecules/`): SearchBar, PriceCard, ServiceOption, FormField
|
||||
3. **Organisms** (`src/components/organisms/`): ServiceSelector, PricingTable, ArrangementForm, Navigation
|
||||
|
||||
## Critical rules
|
||||
|
||||
1. **Every component MUST consume the MUI theme** — never hardcode colours, spacing, typography, or shadows
|
||||
2. **Every token MUST have a `$description`** — this is how agents maintain context about design intent
|
||||
3. **Always read docs/design-system.md** before creating or modifying anything
|
||||
4. **Always check docs/memory/** before starting work — these files contain decisions and state from previous sessions
|
||||
5. **Always update docs/memory/** after completing work — log what was done, decisions made, and open questions
|
||||
6. **Run `npm run build:tokens`** after any token JSON change
|
||||
7. **Verify in Storybook** before marking any component done
|
||||
8. **Follow the component lifecycle** — see `docs/reference/component-lifecycle.md` for the full quality gate sequence (build → QA → polish → present → iterate → normalize → preflight → commit)
|
||||
9. **Commit and push after completing each unit of work** — see Git workflow below
|
||||
|
||||
## Git workflow
|
||||
|
||||
**Remote:** Gitea at `http://192.168.50.211:3000/richie/ParsonsFA.git` (credentials stored via git credential helper)
|
||||
|
||||
**After completing each unit of work** (a component, a token change, a bug fix, etc.):
|
||||
1. Stage the changed files (`git add` — prefer naming specific files over `git add -A`)
|
||||
2. Commit with a clear message describing what was done
|
||||
3. Push to origin (`git push`)
|
||||
|
||||
This is **not optional** — the user relies on the git history for rollback safety. Each commit should represent a coherent, working state (Storybook builds, TypeScript compiles). Do not batch multiple unrelated changes into a single commit.
|
||||
|
||||
**Commit message format:**
|
||||
```
|
||||
Short summary (imperative mood, <70 chars)
|
||||
|
||||
- Bullet points with detail if needed
|
||||
- Reference decision IDs (D001, D002...) when relevant
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
**Branch strategy:** All work on `main` for now. Feature branches when the project grows.
|
||||
This is "morning housekeeping" — the user has approved this and expects it.
|
||||
|
||||
## Memory system
|
||||
|
||||
This project uses structured markdown files for cross-session memory.
|
||||
Before starting any work, read:
|
||||
- `docs/memory/decisions-log.md` — all design decisions with rationale
|
||||
- `docs/memory/component-registry.md` — status of every component
|
||||
- `docs/memory/token-registry.md` — all tokens with values and usage notes
|
||||
- `docs/memory/session-log.md` — recent sessions; older in `docs/memory/archive/`
|
||||
|
||||
**Before starting any work, read these files:**
|
||||
- `docs/memory/decisions-log.md` — All design decisions with rationale
|
||||
- `docs/memory/component-registry.md` — Status of every component (planned/in-progress/done)
|
||||
- `docs/memory/token-registry.md` — All tokens with their current values and usage notes
|
||||
- `docs/memory/session-log.md` — Recent sessions (last 2-3); older sessions in `docs/memory/archive/`
|
||||
|
||||
**Session startup — proactive review pass (do this automatically):**
|
||||
Check `docs/reference/retroactive-review-plan.md` for the current review state. If
|
||||
there are tiers or components that haven't been reviewed yet, run the next review
|
||||
step (typically `/normalize {tier}` or `/audit {component}`) at the start of the
|
||||
session before the user's main request. Keep this to ~30-60 min, then report
|
||||
findings and shift to whatever the user wants to work on. This is "morning
|
||||
housekeeping" — the user has approved this and expects it to happen without asking.
|
||||
|
||||
**After completing work, update:**
|
||||
- The relevant memory files with what changed
|
||||
- `docs/memory/session-log.md` with a summary of what was accomplished and next steps
|
||||
After completing work, update the relevant memory files and `session-log.md`.
|
||||
|
||||
## MCP servers
|
||||
|
||||
- **Figma remote MCP** (`figma-remote-mcp`): Read FA 1.0 designs, extract design context
|
||||
- **Storybook MCP** (`storybook`): Query component library for available components and props
|
||||
- **Figma remote MCP** — read FA 1.0 designs, extract design context
|
||||
- **Storybook MCP** — query component library for available components and props
|
||||
|
||||
Setup instructions in `docs/reference/mcp-setup.md`.
|
||||
Setup instructions: `docs/reference/mcp-setup.md`
|
||||
|
||||
## File conventions
|
||||
## Commit co-author
|
||||
|
||||
- Component folders: PascalCase (`Button/`, `PriceCard/`)
|
||||
- Token files: camelCase (`colours.json`, `typography.json`)
|
||||
- Each component folder contains: `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
|
||||
- CSS custom properties prefix: `--fa-` (e.g., `--fa-color-brand-primary`)
|
||||
- MUI theme paths: follow MUI conventions (`palette.primary.main`)
|
||||
Append to every commit message:
|
||||
```
|
||||
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
## Naming conventions for tokens
|
||||
## Cross-tool workflow
|
||||
|
||||
See `docs/conventions/token-conventions.md` for the full specification.
|
||||
This project uses both Claude Code and Google Antigravity.
|
||||
See `docs/reference/cross-tool-workflow.md` for task routing and coordination.
|
||||
|
||||
Quick reference:
|
||||
- Primitives: `color.blue.500`, `spacing.4`, `fontSize.base`
|
||||
- Semantic: `color.text.primary`, `color.surface.default`, `color.interactive.default`
|
||||
- Component: `button.background.default`, `button.background.hover`
|
||||
Claude Code owns: component building, token creation, code quality, memory updates, git.
|
||||
Antigravity owns: visual QA, browser-based verification, page-level review screenshots.
|
||||
|
||||
72
GEMINI.md
72
GEMINI.md
@@ -1,58 +1,26 @@
|
||||
# FA 2.0 Design System — Antigravity Rules
|
||||
# Antigravity — FA 2.0 Design System
|
||||
|
||||
## Project context
|
||||
Follow all rules in `AGENTS.md`. This file contains Antigravity-specific behaviour only.
|
||||
|
||||
Funeral Arranger (funeralarranger.com.au) design system rebuild. Parsons is the
|
||||
client. The design language must be warm, professional, trustworthy, and calm.
|
||||
Users are often in distress.
|
||||
|
||||
## Tech stack
|
||||
|
||||
- React 18 + TypeScript
|
||||
- Material UI (MUI) v5
|
||||
- Storybook 8+ (running on localhost:6006)
|
||||
- Style Dictionary for token transformation
|
||||
- W3C DTCG token format
|
||||
|
||||
## Hard rules
|
||||
|
||||
1. **Never hardcode colours, spacing, typography, or shadows** — always consume the MUI theme (`theme.palette.*`, `theme.spacing()`, `theme.typography.*`) or CSS custom properties (`var(--fa-*)`)
|
||||
2. **Never use raw hex values in components** — map to semantic tokens
|
||||
3. **Follow atomic design tiers:** atoms → molecules → organisms → templates → pages
|
||||
4. **Component folders:** PascalCase, each contains `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
|
||||
5. **Token files:** camelCase in `tokens/` directory (primitives → semantic → component tiers)
|
||||
6. **CSS custom properties prefix:** `--fa-`
|
||||
7. **Error styling uses copper (#B0610F)** not red — this is intentional for grief-sensitive context
|
||||
8. **Copy tone:** warm but not gushy. Understated empathy. Let UI structure be the empathy.
|
||||
|
||||
## Token access convention
|
||||
|
||||
- Semantic tokens: `theme.palette.*`, `theme.typography.*`, `theme.spacing()`
|
||||
- Component tokens: `var(--fa-component-property-state)`
|
||||
- Never mix — semantic via theme, component via CSS vars
|
||||
|
||||
## Storybook
|
||||
|
||||
Dev server runs on `localhost:6006`. When verifying components visually, navigate
|
||||
to the specific story URL. Story IDs follow the pattern:
|
||||
`/story/{tier}-{componentname}--{variantname}`
|
||||
|
||||
## File structure
|
||||
|
||||
```
|
||||
src/components/atoms/ — Button, Input, Typography, Card, etc.
|
||||
src/components/molecules/ — SearchBar, PriceCard, ServiceOption, etc.
|
||||
src/components/organisms/ — Navigation, Footer, ArrangementDialog, etc.
|
||||
src/components/templates/ — WizardLayout
|
||||
src/components/pages/ — IntroStep, ProvidersStep, etc. (wizard steps)
|
||||
tokens/primitives/ — Raw values (hex, px, font names)
|
||||
tokens/semantic/ — Design intent (color.text.primary)
|
||||
tokens/component/ — Per-component tokens
|
||||
```
|
||||
|
||||
## When making visual changes
|
||||
## Visual verification
|
||||
|
||||
When reviewing or making visual changes:
|
||||
1. Make the code change
|
||||
2. Open the Storybook story in the browser to verify
|
||||
2. Open the Storybook story in the browser at `localhost:6006`
|
||||
3. Screenshot and check spacing, alignment, visual weight
|
||||
4. Self-correct if something looks off before presenting
|
||||
|
||||
Story URL pattern: `/story/{tier}-{componentname}--{variantname}`
|
||||
|
||||
## Cross-tool workflow
|
||||
|
||||
This project uses both Claude Code and Google Antigravity.
|
||||
See `docs/reference/cross-tool-workflow.md` for task routing and coordination.
|
||||
|
||||
Antigravity owns: visual QA, browser verification, page-level review screenshots.
|
||||
Claude Code owns: component building, token creation, code quality, memory updates, git.
|
||||
|
||||
## Workflows
|
||||
|
||||
Custom workflows available in `.agent/workflows/`:
|
||||
`fa-session-start`, `fa-preflight`, `fa-token-sync`, `fa-visual-qa`, `fa-build-component`, `fa-page-review`
|
||||
|
||||
184
docs/reference/cross-tool-workflow.md
Normal file
184
docs/reference/cross-tool-workflow.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Cross-Tool Workflow: Claude Code + Google Antigravity
|
||||
|
||||
## How the tools work together
|
||||
|
||||
**Claude Code** (terminal) — code generation, refactoring, quality analysis, memory
|
||||
management. Has 18 custom skills, 3 agents, MCP access (Figma, Storybook).
|
||||
Strengths: deep code reasoning, multi-file refactors, token architecture, grief-sensitive
|
||||
copy review, git operations.
|
||||
|
||||
**Antigravity** (IDE) — visual verification, browser interaction, page-level review.
|
||||
Has 6 custom workflows in `.agent/workflows/`. Strengths: built-in browser for
|
||||
Storybook verification, screenshot comparison across breakpoints, multi-agent
|
||||
parallelism via Manager View.
|
||||
|
||||
**Both read:** `AGENTS.md` (shared rules), `docs/memory/` (shared state), all source files.
|
||||
|
||||
---
|
||||
|
||||
## Task routing
|
||||
|
||||
### Always Claude Code
|
||||
|
||||
- Creating new components (`/build-atom`, `/build-molecule`, `/build-organism`)
|
||||
- Token creation and architecture (`/create-tokens`, `/sync-tokens`)
|
||||
- Code quality analysis (`/audit`, `/critique`, `/harden`, `/normalize`)
|
||||
- Writing tests and stories (`/write-tests`, `/write-stories`)
|
||||
- Visual polish skills (`/polish`, `/typeset`, `/adapt`, `/quieter`, `/clarify`)
|
||||
- Memory file updates (decisions-log, component-registry, session-log)
|
||||
- Git operations (commit, push)
|
||||
- Multi-file refactors
|
||||
- Figma MCP interactions (design extraction)
|
||||
|
||||
### Always Antigravity
|
||||
|
||||
- Browser-based visual QA (`/fa-visual-qa` workflow)
|
||||
- Screenshot comparison across breakpoints (375/768/1280px)
|
||||
- Page-level visual review (`/fa-page-review` workflow)
|
||||
- Storybook visual regression checks
|
||||
|
||||
### Either tool (user's choice)
|
||||
|
||||
- Preflight checks (Claude: `/preflight` | Antigravity: `/fa-preflight`)
|
||||
- Token sync rebuild (Claude: `/sync-tokens` | Antigravity: `/fa-token-sync`)
|
||||
- Session status report (Claude: `/status` | Antigravity: `/fa-session-start`)
|
||||
- Reading and analysing existing code
|
||||
- Copy and content review
|
||||
|
||||
---
|
||||
|
||||
## The sandwich workflow
|
||||
|
||||
Every significant change should follow a three-step pattern that uses both tools.
|
||||
|
||||
### For new components or features
|
||||
|
||||
1. **Plan (Claude Code):** Read memory files, check registry, design the approach
|
||||
2. **Build (Claude Code):** Implement — component, tokens, stories, tests
|
||||
3. **Verify (Antigravity):** Open in Storybook, screenshot at 3 breakpoints, report issues
|
||||
|
||||
### For page tweaking (current phase)
|
||||
|
||||
1. **Assess (Antigravity):** Run `/fa-page-review`, screenshot current state, identify issues
|
||||
2. **Fix (Claude Code):** Make targeted fixes to spacing, copy, alignment, responsive
|
||||
3. **Verify (Antigravity):** Re-run `/fa-visual-qa`, confirm fixes, screenshot final state
|
||||
|
||||
The sandwich ensures no change goes live without both code quality AND visual verification.
|
||||
|
||||
---
|
||||
|
||||
## Quality gates
|
||||
|
||||
The 10-stage component lifecycle (`docs/reference/component-lifecycle.md`) applies
|
||||
regardless of which tool does the work.
|
||||
|
||||
| Stage | Primary tool | Gate |
|
||||
|-------|-------------|------|
|
||||
| 1. BUILD | Claude Code | — |
|
||||
| 2. STORIES | Claude Code | — |
|
||||
| 3. INTERNAL QA | Claude Code (`/audit`, `/critique`, `/harden`) | P0 = blocking |
|
||||
| 4. FIX | Claude Code | Until P0/P1 = 0 |
|
||||
| 5. POLISH | Claude Code (`/polish`, `/typeset`, `/adapt`) | — |
|
||||
| 6. PRESENT | Antigravity (`/fa-visual-qa`) | Visual sign-off |
|
||||
| 7. ITERATE | Both (Claude fixes, Antigravity verifies) | User approves |
|
||||
| 8. NORMALIZE | Claude Code (`/normalize`) | — |
|
||||
| 9. PREFLIGHT | Either (`/preflight` or `/fa-preflight`) | Critical = blocking |
|
||||
| 10. COMMIT | Claude Code | — |
|
||||
|
||||
**Enforcement:** No component moves past PRESENT without Antigravity visual sign-off.
|
||||
No component moves to COMMIT without preflight passing.
|
||||
|
||||
---
|
||||
|
||||
## File ownership boundaries
|
||||
|
||||
### Current phase (frontend only)
|
||||
|
||||
| Scope | Claude Code | Antigravity |
|
||||
|-------|------------|-------------|
|
||||
| `src/components/**/*.tsx` | write | read only |
|
||||
| `src/components/**/*.stories.tsx` | write | read only |
|
||||
| `src/components/**/index.ts` | write | read only |
|
||||
| `tokens/**/*.json` | write | read only |
|
||||
| `src/theme/**` | write | read only |
|
||||
| `docs/memory/**` | write | read only |
|
||||
| `docs/conventions/**`, `docs/reference/**` | write | read only |
|
||||
| `.agent/workflows/*.md` | read only | write (own workflows) |
|
||||
| `AGENTS.md` | write (coordinate first) | write (coordinate first) |
|
||||
| `CLAUDE.md` | write | never |
|
||||
| `GEMINI.md` | never | write |
|
||||
|
||||
### When backend starts (Payload CMS)
|
||||
|
||||
- **Backend agent writes:** `src/payload/**`, `src/api/**`, database schemas, server config
|
||||
- **Frontend agents never touch:** anything in `src/payload/` or `src/api/`
|
||||
- **Backend agent never touches:** `src/components/**`, `tokens/**`, `src/theme/**`
|
||||
- **Shared contract:** `documentation/flow-definition.yaml` is the interface between
|
||||
frontend and backend. Field names, step IDs, and visibility rules in that file
|
||||
dictate both component props and API data shapes. Changes require both sides
|
||||
to acknowledge.
|
||||
|
||||
### Conflict resolution
|
||||
|
||||
- If two agents need to edit the same file: **STOP**, flag it in `docs/memory/session-log.md`,
|
||||
let the user decide who proceeds.
|
||||
- If agents produce conflicting output: `docs/memory/decisions-log.md` is the tiebreaker.
|
||||
Whoever's approach matches a logged decision wins.
|
||||
|
||||
---
|
||||
|
||||
## Error mitigation
|
||||
|
||||
### Pre-flight checklist (before any agent work)
|
||||
|
||||
- [ ] Read `docs/memory/session-log.md` — is another agent mid-task?
|
||||
- [ ] Read `docs/memory/component-registry.md` — is the target component in-progress by someone else?
|
||||
- [ ] Confirm file ownership — am I allowed to write these files?
|
||||
- [ ] Storybook running? (`localhost:6006`)
|
||||
- [ ] Git clean? No uncommitted changes from a previous session
|
||||
|
||||
### Memory file update protocol
|
||||
|
||||
1. Read the file before writing (always)
|
||||
2. Append, do not overwrite existing entries
|
||||
3. Use the established format (each file documents its own format)
|
||||
4. Include decision IDs (D001, D002...) for traceability
|
||||
5. Log agent name and date in every session-log entry
|
||||
|
||||
### Verification after every change
|
||||
|
||||
- TypeScript compiles: `npx tsc --noEmit`
|
||||
- Storybook renders the specific story (not just builds)
|
||||
- Visual check: at least desktop breakpoint for small changes, all three for layout changes
|
||||
- Token sync: if tokens changed, run `npm run build:tokens` and verify output
|
||||
|
||||
### When agents produce conflicting output
|
||||
|
||||
1. Check `docs/memory/decisions-log.md` for a prior decision
|
||||
2. If a decision exists: follow it, flag the conflict in session-log
|
||||
3. If no decision exists: **STOP**, do not proceed, ask the user
|
||||
4. Never silently override another agent's work
|
||||
|
||||
### Common failure modes and recovery
|
||||
|
||||
| Failure | Symptom | Recovery |
|
||||
|---------|---------|----------|
|
||||
| Stale tokens | Generated files older than source JSON | Run `npm run build:tokens` |
|
||||
| Hardcoded values | Hex colours in `.tsx` files | Run preflight scan, replace with theme refs |
|
||||
| Memory drift | Session log not updated | Always update session-log as last step |
|
||||
| Story rendering failure | Component changed but stories broken | Run `/write-stories` to regenerate |
|
||||
| File ownership violation | Two agents edited same file | `git diff` to see both changes, manually merge |
|
||||
|
||||
---
|
||||
|
||||
## Adapting for backend work
|
||||
|
||||
When Payload CMS implementation begins:
|
||||
|
||||
1. Add a `## Backend (Payload CMS)` section to `AGENTS.md` with Payload-specific rules
|
||||
2. Add backend file ownership to the boundaries above
|
||||
3. `documentation/flow-definition.yaml` becomes the API contract — field names, step IDs,
|
||||
and visibility rules dictate both frontend props and backend data shapes
|
||||
4. Backend agent reads `documentation/flow-definition.yaml` and `documentation/steps/*.yaml`
|
||||
as its primary specifications
|
||||
5. Frontend agents continue unchanged — the boundary is the data interface, not the UI
|
||||
Reference in New Issue
Block a user