thomas-agentkit 0.8.0 → 0.9.0-alpha.1

package/templates/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 Follow `AGENTS.md` first. It is the primary source of truth for this repository's AI-agent guidance.
 
-Do not load companion files for routine coding. Use `AGENTS.md` triggers: change explanation after file edits; `CODE-QUALITY.md` for review/refactors; design-system path or `DESIGN-SYSTEM.md` for UI; `TESTING.md`, `SECURITY-CHECKLIST.md`, or `STACK.md` when present and relevant; planning templates only when explicitly requested.
+Do not load companion files for routine coding. Use `AGENTS.md` triggers: change explanation after file edits; `CODE-QUALITY.md` for review/refactors; `DESIGN.md` or project design path for UI; `TESTING.md`, `SECURITY-CHECKLIST.md`, or `STACK.md` when present and relevant; planning templates only when explicitly requested.
 
 For files covered by additional GitHub instructions under `.github/instructions/`, apply those path-specific instructions together with this file.
 

package/templates/AGENTS.md

@@ -19,7 +19,7 @@ For routine bugfixes and small features, do not open `WORKFLOWS.md`, planning te
 | Trigger | Action |
 | --- | --- |
 | Any file edits (final message) | Use the change-explanation format in **After Coding (Required)**; see `CHANGE-EXPLANATION.md` for detail |
-| UI, components, styling, layout | Read `[design system path, e.g. docs/design-system.md]` or `DESIGN-SYSTEM.md` |
+| UI, components, styling, layout | Read `DESIGN.md` or `[design system path, e.g. docs/design-system.md]` when set |
 | Review, refactor, dependencies | Read `CODE-QUALITY.md` |
 | Tests, fixtures, QA strategy | Read `TESTING.md` if present |
 | Auth, permissions, secrets, PII | Read `SECURITY-CHECKLIST.md` if present |

package/templates/WORKFLOWS.md

@@ -14,7 +14,7 @@ Optional process reference for repositories that installed the **full** AgentKit
 | Tiny obvious fix | Implement directly; no formal planning doc |
 | User-facing feature or product uncertainty (planning requested) | Create from `PRD-TEMPLATE.md` under `[briefs path, e.g. docs/briefs]` |
 | Multi-file engineering with risk (planning requested) | Create from `IMPLEMENTATION-BRIEF-TEMPLATE.md` under `[briefs path, e.g. docs/briefs]` |
-| UI, styling, layout, navigation, components | `DESIGN-SYSTEM.md` or project design-system path |
+| UI, styling, layout, navigation, components | `DESIGN.md` or project design path |
 | Security-sensitive change | `SECURITY-CHECKLIST.md` if present |
 | Test strategy or test implementation | `TESTING.md` if present |
 | Review, refactor, dependencies | `CODE-QUALITY.md` |

package/templates/design-systems/apple.md

@@ -1,236 +1,101 @@
-# [Project Name] Design System - Apple-Inspired Foundations
+# [Project Name] Design — Apple
 
-This design system codifies the visual and interaction principles for [Project Name].
+Design spec for [Project Name]. Map semantic tokens to `[theme stylesheet path, e.g. src/styles.css]` or your Tailwind theme. Do not hardcode literal colors in components.
 
-It is the default source of truth for app shell layout, navigation, lists, controls, and page chrome in this repository.
+## Overview
 
-All colors, typography families, and radii must be consumed through semantic tokens in `[theme stylesheet path, e.g. src/styles.css]` or a dedicated theme stylesheet imported there. Components must not hardcode literal color values or font family names.
+Photography-first marketing: full-bleed product tiles alternating light and dark canvases, confident display type, and a single Action Blue accent for interactive elements. UI recedes so product imagery leads. One soft product shadow is allowed on photographic renders — never on cards or buttons.
 
-## 1) Surface And Color
+**Key characteristics:**
+- Tile alternation (white/parchment ↔ near-black) as section divider
+- Single structural accent (`{colors.primary}`) for CTAs and links
+- Pill CTAs (`{rounded.pill}`) vs compact utility rects (`{rounded.sm}`)
+- Display tracking pulls negative at large sizes; body at 17px
+- No decorative gradients; atmosphere from photography only
 
-### Philosophy
+## Colors
 
-The interface reads as a calm, spacious canvas. Separation comes from spacing, typography, subtle grouped inset surfaces when grouping controls, and structural seams—not stacked decorative containers.
+### Brand & Accent
+- `{colors.primary}` — Action Blue (CTAs, links, focus)
+- `{colors.primary-hover}`, `{colors.primary-focus}` — hover and focus variants
+- `{colors.on-primary}` — text on primary fills
 
-### Token Roles
+### Surface
+- `{colors.canvas}` — pure white tile
+- `{colors.canvas-parchment}` — off-white alternating tile
+- `{colors.surface-tile-1}` through `{colors.surface-tile-3}` — dark tile steps
+- `{colors.surface-black}` — nav bar, video void
+- `{colors.hairline}` — card and divider borders
 
-Define semantic CSS custom properties and map them to the project's theme tokens:
+### Text
+- `{colors.ink}` — near-black on light; `{colors.body-on-dark}` on dark tiles
+- `{colors.body-muted}`, `{colors.ink-muted-48}` — secondary and disabled
 
-- `--background`: app canvas
-- `--foreground`: primary text
-- `--muted-foreground`: secondary/meta text
-- `--border`: structural seams
-- `--card`: grouped inset surfaces (forms, settings groups, grouped lists) and dialogs/popovers
-- `--popover`: overlay surfaces
-- `--accent`: subtle hover/active in content areas
-- `--sidebar`: sidebar canvas
-- `--sidebar-accent`: hover/active in sidebar
-- `--primary`: brand and primary CTA (system blue)
-- `--destructive`: danger actions
-- `--ring`: focus ring
+## Typography
 
-### Rules
+- Display: system sans (SF Pro Display stack); body: SF Pro Text stack; mono for code snippets
+- Substitute: Inter at 500/600/700 with tightened tracking; JetBrains Mono for mono
 
-- Canvas-first for browsing and routine reading; use grouped inset surfaces only where controls belong together (forms, settings, grouped lists).
-- No decorative gradients on product surfaces.
-- Use one accent color, `--primary`, for brand and primary actions. Map `--primary` to system blue (for example `#007AFF` in light, `#0A84FF` in dark), expressed via tokens—not literals in components.
-- Prefer spacing and typographic hierarchy over extra backgrounds.
-- Keep all colors tokenized and theme-ready for light and dark modes.
+| Token | Use |
+|---|---|
+| `{typography.display-xl}` | Hero headline |
+| `{typography.display-lg}` | Section openers |
+| `{typography.lead}` | Tile taglines |
+| `{typography.body}` | Default body (17px) |
+| `{typography.button}` | Button labels |
+| `{typography.nav-link}` | Global nav |
 
-## 2) Typography
+### Principles
+- Headlines weight 600 with negative tracking; body 400
+- Weight 300 rare and deliberate for large airy reads
+- No weight 500 in the ladder
 
-### Families
+## Layout
 
-- Interface text: `font-sans` backed by `--font-sans` (map theme to `-apple-system, BlinkMacSystemFont, "SF Pro Text", "Inter", system-ui, sans-serif`).
-- Code, IDs, and timestamps: `font-mono` backed by `--font-mono` (map theme to `"SF Mono", ui-monospace, "JetBrains Mono", monospace`).
+- Base unit: 8px; section padding `{spacing.section}` ~80px
+- Max width ~1280px; tile stacks edge-to-edge vertically
+- Whitespace = canvas color change between tiles
 
-Do not reference literal font families in component files.
+## Elevation
 
-### Scale
+Flat tiles default. One product shadow on renders resting on surface. Backdrop blur on frosted sub-nav and sticky bars.
 
-- Page heading: `text-2xl`, `font-semibold`
-- Section heading: `text-lg`, `font-semibold`
-- Body / row label: `text-sm`, `font-normal` to `font-medium`
-- Meta / secondary: `text-xs`, `font-normal`
-- Nav section label: `text-xs uppercase tracking-wide`, `font-medium`
-- Tiny helper: `text-[11px]`, `font-normal`
+## Shapes
 
-### Rules
+| Token | Use |
+|---|---|
+| `{rounded.sm}` 8px | Utility buttons, inputs |
+| `{rounded.lg}` 18px | Cards |
+| `{rounded.pill}` | Primary/secondary pill CTAs |
+| `{rounded.none}` | Full-bleed tiles |
 
-- Headlines are clear and restrained; prefer slightly tighter tracking on large display sizes (`tracking-tight` where appropriate).
-- Use comfortable line height for body (`leading-normal` or `leading-relaxed`).
-- Reserve uppercase for nav section labels and compact metadata.
+## Components
 
-## 3) Navigation
+- `{components.button-primary}` — Action Blue pill
+- `{components.button-secondary}` — charcoal pill with hairline
+- `{components.product-tile-light}`, `{components.product-tile-dark}` — full-bleed tiles
+- `{components.store-utility-card}` — bordered white card
+- `{components.global-nav}`, `{components.sub-nav-frosted}` — two-row nav
+- `{components.text-input}` — surface fill, pill or md radius
 
-### Structure
+## Do's and Don'ts
 
-1. Header row: identity, search, and create action.
-2. Primary links.
-3. Collapsible grouped links.
-4. Lightweight footer affordance for help or docs.
+### Do
+- Use `{colors.primary}` only for interactive signals
+- Alternate light and dark tiles for rhythm
+- Apply `scale(0.95)` as button press state
+- Keep global nav on `{colors.surface-black}`
 
-### Item Styling
+### Don't
+- Don't add decorative gradients or second accents
+- Don't pill-round utility buttons
+- Don't use true `#000000` as canvas
+- Don't shadow cards or buttons
 
-- Default: `text-sm`, muted foreground.
-- Hover: subtle `sidebar-accent` background.
-- Active: full-width rounded rectangle, medium weight.
-- Icon size: 14px to 16px.
-- Nav row baseline: `rounded-lg h-9 px-3`.
+## Responsive Behavior
 
-### Collapse Behavior
+Nav hamburger below 768px. Card grids 3→2→1. Display scales from 80px toward 36px on small phones. Touch targets ≥44px.
 
-- Expanded width: `15rem` or 240px.
-- Collapsed width: `3rem` or 48px, icon-only with tooltip.
-- Mobile: sheet/drawer using expanded width.
-- Keyboard shortcut: support the project's standard sidebar toggle shortcut, e.g. `Cmd+B`.
+## Token Mapping
 
-## 4) Layout Regions
-
-### App Shell
-
-- Sidebar: fixed left, full viewport height, right seam border.
-- Content: `flex-1 min-w-0`, same background canvas.
-- Optional inspector: right panel, `22rem` to `28rem`, collapsible.
-
-### Common Page Patterns
-
-- List workspace: toolbar plus scrollable list.
-- Detail view: breadcrumbs/title plus body and optional inspector.
-- Editor split: left rail plus center editor.
-- Settings split: nav plus forms inside grouped inset surfaces.
-
-### Toolbar Strip
-
-- Height: `h-12`.
-- Bottom seam: `border-b border-border/50`.
-- No separate heavy background block.
-
-### Page padding
-
-- Content padding: `p-4` to `p-6` (16px to 24px) for comfortable reading rhythm.
-
-## 5) Interactive Elements
-
-### Buttons
-
-- Primary: solid `primary` (system blue).
-- Secondary: neutral fill.
-- Ghost: transparent with subtle hover fill.
-- Destructive: `destructive` only for dangerous confirms.
-- Icon-only: `size-9` or `size-10`, ghost, tooltip.
-
-Rules:
-
-- Default radius: `rounded-lg` using the tokenized radius scale.
-- Sparse shadows; prefer borders for separation on web.
-- Primary buttons are intentional—do not pepper every row with a primary.
-
-### Inputs
-
-- Default height: `h-9`; relaxed contexts: `h-10` to `h-12`.
-- Tokenized input background and border.
-- Visible focus ring: `ring-2 ring-ring` with comfortable offset.
-- Labels above fields. Do not use floating labels by default.
-
-### Menus / Popovers / Dialogs
-
-- Tokenized `popover` surface and subtle border.
-- Typography: `text-sm` for menus; `text-sm` to `text-base` for dialogs as needed.
-- Comfortable spacing.
-- Dialog actions align right: secondary then primary.
-
-## 6) Lists And Data
-
-### Row Anatomy
-
-- Relaxed, single-line by default where possible.
-- Hover uses subtle accent fill.
-- Selected row uses tinted fill derived from `--primary` (for example ~12% opacity in light, ~24% in dark) plus medium weight.
-- Avoid per-row borders; separate by spacing and padding rhythm.
-
-### Grouping And Tables
-
-- Group labels are muted; children are indented or wrapped in grouped inset surfaces.
-- Table headers: compact meta style; avoid heavy uppercase unless it aids scanability.
-- No zebra striping or heavy gridlines.
-
-## 7) Status And Feedback
-
-- Status: small dots or SF-symbol-style glyphs with semantic meaning (optional).
-- Loading: skeletons for content, spinners only for inline actions.
-- Toasts: soft shadow, corner-pinned or non-intrusive, auto-dismiss.
-- Empty states: icon, short message, and optional single CTA.
-
-## 8) Motion
-
-- Motion confirms state changes; it is never decorative.
-- Micro interactions: about 200ms.
-- Layout shifts: about 300ms to 350ms.
-- Preferred easing: `cubic-bezier(0.25, 0.1, 0.25, 1)`.
-- Sheets and popovers may use a subtle spring-like overshoot when it aids affordance; keep amplitude low on web.
-- Respect `prefers-reduced-motion` with near-instant transitions.
-
-## 9) Spacing System
-
-Base unit is 4px, using the project's spacing scale.
-
-- `p-1` or 4px: tight internals.
-- `p-2` or 8px: compact section padding.
-- `p-3` or 12px: dense content blocks.
-- `p-4` or 16px: page-level rhythm.
-- `p-6` or 24px: relaxed sections when the layout calls for breathing room.
-
-Density guidelines:
-
-- Sidebar: relaxed, `h-9` rows.
-- Content: moderate, `h-10` to `h-12` rows.
-- Forms/settings: relaxed, `h-12` to `h-14` rows.
-
-## 10) Accessibility
-
-- Full keyboard navigation for all controls.
-- Consistent visible focus styles.
-- Semantic landmarks such as `nav` and `main`.
-- Collapsibles expose `aria-expanded`.
-- Ensure WCAG AA contrast in both themes.
-
-## 11) Anti-Patterns
-
-- Do not wrap routine browsing content in grouped inset surfaces.
-- Do not introduce multiple accent colors.
-- Do not add decorative gradients behind core product surfaces.
-- Do not stack multiple competing toolbars.
-- Do not color-code nav icons.
-- Do not use heavy drop shadows for everyday chrome.
-- Do not hardcode colors or font families in components.
-
-## 12) Applying This System
-
-### Where Values Live
-
-- Theme tokens and base layer: `[theme stylesheet path, e.g. src/styles.css]`.
-- App shell composition: `[route/layout path, e.g. src/routes or app]`.
-- Reusable UI primitives: `[components path, e.g. src/components/ui]`.
-
-### New Component Checklist
-
-1. Canvas-first or justified grouped inset for grouped controls—not card-first for everything?
-2. Uses 2-3 text hierarchy levels max?
-3. Has subtle hover and clear active states?
-4. Uses primary color only where needed?
-5. Uses spacing rhythm in 4px increments?
-6. Has complete keyboard and focus behavior?
-7. Uses token-driven colors and fonts?
-8. Works in light and dark themes?
-
-### For Coding Agents
-
-- Read this file before changing UI, layout, navigation, styling, or components.
-- Prefer existing UI primitives and local layout patterns.
-- Do not introduce new visual language without documenting the reason in the implementation brief or PR.
-- Before handoff, check responsive behavior, focus states, text overflow, loading states, empty states, and token usage.
-
-### Working Rule
-
-Default to these principles unless a deliberate exception is documented in a feature-specific spec.
+Bind roles in `[theme stylesheet path, e.g. src/styles.css]`.

package/templates/design-systems/cursor.md

@@ -0,0 +1,95 @@
+# [Project Name] Design — Cursor
+
+Design spec for [Project Name]. Map semantic tokens to `[theme stylesheet path, e.g. src/styles.css]` or your Tailwind theme.
+
+## Overview
+
+Editorial developer brand on warm cream canvas: quiet display weight 400, single Cursor Orange accent used scarcely, and IDE mockup cards as the primary decorative system. AI timeline pastels are scoped to in-product agent visualizations only.
+
+**Key characteristics:**
+- Warm cream `{colors.canvas}` — never pure white page floor
+- Single CTA color `{colors.primary}` (orange)
+- Display weight 400; negative tracking on display only
+- JetBrains Mono on every code surface
+- Hairline-only depth; no drop shadows
+- Timeline pastels: thinking, grep, read, edit, done — agent UI only
+
+## Colors
+
+### Brand & Accent
+- `{colors.primary}`, `{colors.primary-active}`, `{colors.on-primary}`
+
+### Surface
+- `{colors.canvas}` — warm cream page floor
+- `{colors.canvas-soft}` — IDE pane background in mockups
+- `{colors.surface-card}` — white cards on cream
+- `{colors.surface-strong}` — badges
+- `{colors.hairline}`, `{colors.hairline-soft}`, `{colors.hairline-strong}`
+
+### Text
+- `{colors.ink}`, `{colors.body}`, `{colors.body-strong}`, `{colors.muted}`, `{colors.muted-soft}`
+
+### Timeline (in-product only)
+- `{colors.timeline-thinking}`, `{colors.timeline-grep}`, `{colors.timeline-read}`, `{colors.timeline-edit}`, `{colors.timeline-done}`
+
+### Semantic
+- `{colors.semantic-success}`, `{colors.semantic-error}`
+
+## Typography
+
+- CursorGothic substitute: Inter weight 400/500/600; JetBrains Mono for code
+- Display 400 with negative tracking; body 400 at 16px
+
+| Token | Use |
+|---|---|
+| `{typography.display-mega}` | Homepage hero |
+| `{typography.display-lg}` | Section heads |
+| `{typography.body-md}` | Default body |
+| `{typography.code}` | Code blocks |
+| `{typography.button}` | CTA labels |
+
+## Layout
+
+- Base 4px; `{spacing.section}` 80px; max width ~1200px
+- Feature grids 3-up → 2-up → 1-up; footer 5-column desktop
+
+## Elevation
+
+Hairlines + white-on-cream contrast only. IDE mockup cards are the elevated element.
+
+## Shapes
+
+| Token | Use |
+|---|---|
+| `{rounded.md}` 8px | CTAs, inputs |
+| `{rounded.lg}` 12px | Cards, IDE panes |
+| `{rounded.pill}` | Timeline pills, badges |
+
+## Components
+
+- `{components.button-primary}` — orange CTA `{rounded.md}`
+- `{components.button-download}` — ink fill inverted CTA
+- `{components.hero-band}`, `{components.ide-mockup-card}`, `{components.ide-pane}`
+- `{components.timeline-pill-*}` — five stage variants
+- `{components.feature-card}`, `{components.pricing-tier-card}`
+- `{components.top-nav}`, `{components.footer}`
+
+## Do's and Don'ts
+
+### Do
+- Keep display at weight 400
+- Use timeline pastels only in agent timeline UI
+- Render code in JetBrains Mono
+
+### Don't
+- Don't add drop shadows
+- Don't use timeline pastels as system action colors
+- Don't bold display headlines
+
+## Responsive Behavior
+
+Nav hamburger below 768px. Hero display 72→32px mobile. IDE mockup collapses to single pane.
+
+## Token Mapping
+
+Bind roles in `[theme stylesheet path, e.g. src/styles.css]`.

package/templates/design-systems/framer.md

@@ -0,0 +1,95 @@
+# [Project Name] Design — Framer
+
+Design spec for [Project Name]. Map semantic tokens to `[theme stylesheet path, e.g. src/styles.css]` or your Tailwind theme.
+
+## Overview
+
+Dark poster marketing: near-black canvas, oversized white display type with extreme negative tracking, white pill primary CTAs, and gradient spotlight cards as individual showcase tiles — never section backgrounds. Single sky-blue accent for links and focus only.
+
+**Key characteristics:**
+- Dark-only marketing; no light mode
+- `{colors.primary}` = white (CTA fill and ink on dark)
+- `{colors.accent-blue}` — hyperlinks, focus, selection only
+- Gradient spotlight cards (violet, magenta, orange, coral) as scarce atmosphere
+- Inter Variable body with OpenType variants when available
+- Pill CTAs (`{rounded.pill}`); charcoal secondary pills
+
+## Colors
+
+### Brand & Accent
+- `{colors.primary}` — white (CTA, headlines, body on canvas)
+- `{colors.accent-blue}` — signal blue (links, focus ring)
+- `{colors.on-primary}` — text on white pills (dark)
+
+### Surface
+- `{colors.canvas}` — near-black page
+- `{colors.surface-1}`, `{colors.surface-2}` — card and button lifts
+- `{colors.hairline}`, `{colors.hairline-soft}`
+- `{colors.ink}`, `{colors.ink-muted}`
+
+### Gradients (card fills only)
+- `{colors.gradient-violet}`, `{colors.gradient-magenta}`, `{colors.gradient-orange}`, `{colors.gradient-coral}`
+
+## Typography
+
+- Display: GT Walsheim substitute (Mona Sans, Geist, or Inter 600–700 with tight tracking)
+- Body: Inter Variable with `cv01`, `cv05`, `cv09`, `cv11`, `ss03`, `ss07` when supported
+
+| Token | Use |
+|---|---|
+| `{typography.display-xxl}` | 110px hero |
+| `{typography.display-xl}` | 85px section |
+| `{typography.body}` | 15px default |
+| `{typography.button}` | Pill labels |
+
+### Principles
+- Tracking scales hard with size (-5.5px at largest display)
+- Weight band: 400 body, 500 display/buttons
+- Tight line-heights (~1.30 body)
+
+## Layout
+
+- Base 5px increments; `{spacing.section}` 96px
+- Max ~1199px; card grids 2-up → 1-up below 810px
+
+## Elevation
+
+Surface lift (canvas → surface-1 → surface-2). Light-edge shadow on floating mockup cards. Blue ring for focus.
+
+## Shapes
+
+| Token | Use |
+|---|---|
+| `{rounded.pill}` 100px | All text CTAs |
+| `{rounded.xl}` 20px | Pricing, mockup tiles |
+| `{rounded.xxl}` 30px | Gradient spotlight cards |
+
+## Components
+
+- `{components.button-primary}` — white pill
+- `{components.button-secondary}` — charcoal pill
+- `{components.gradient-spotlight-card}` — atmospheric variant tiles
+- `{components.pricing-card}`, `{components.template-card}`, `{components.product-mockup-tile}`
+- `{components.top-nav}`, `{components.footer}`
+
+## Do's and Don'ts
+
+### Do
+- Push negative display tracking aggressively
+- Use accent blue only for links and focus
+- Limit gradient spotlight cards to 1–2 per long page
+- Keep CTAs pill-shaped
+
+### Don't
+- Don't use accent blue as CTA fill
+- Don't apply gradients to whole sections
+- Don't ship light mode
+- Don't square off CTAs
+
+## Responsive Behavior
+
+Nav hamburger below 810px. Display scales 110→62→32px. Pricing table becomes accordion on mobile.
+
+## Token Mapping
+
+Bind roles in `[theme stylesheet path, e.g. src/styles.css]`.