@vextlabs/theron-cli 0.2.1 → 0.4.0

package/skills/competitive-teardown.md

@@ -0,0 +1,223 @@
+---
+name: competitive-teardown
+description: Tear down a named AI/SaaS competitor end-to-end — positioning, ICP, pricing/packaging, product strengths and gaps, GTM motion, moat, and the specific wedges where we win or lose — grounded in public evidence; outputs a ranked battlecard and a single recommended attack vector.
+allowed-tools: Read, WebSearch, WebFetch, Write
+---
+
+KEY PRINCIPLE: A competitive teardown is only as valuable as its honesty about where we lose — a battlecard that only lists wins trains your team to walk into ambushes. Every "WHERE WE WIN" entry must have a matching "WHERE WE LOSE / NOT YET" entry; asymmetry is a planning landmine, not a confidence signal.
+
+═══ HARD RULES ═══
+
+1. NEVER assert a positioning claim about the competitor without citing the specific page, ad copy, job post, or earnings call it came from — label every claim with its source type (website, LinkedIn, G2 review, SEC filing, podcast, etc.).
+2. NEVER state a competitor's revenue, valuation, ARR, or headcount as fact unless the number comes from a public filing, verified press release, or named credible source — label all estimates "est." with the inference method (e.g., "est. $8M ARR — inferred from 40-seat ACV × disclosed logo count").
+3. NEVER conflate "they market X" with "they ship X" — product claims must be verified against changelog entries, API docs, or independent user reviews, not marketing copy alone.
+4. NEVER compare our product to theirs on dimensions we have not ourselves measured or experienced firsthand; flag untested dimensions explicitly as UNVERIFIED.
+5. NEVER recommend a competitive wedge that requires us to abandon our core strategic position (receipted personalization + own-weights serving + auditable agency) — only wedges that sharpen it.
+6. NEVER treat G2 / Capterra ratings as representative without checking: (a) total review count, (b) recency distribution, (c) whether reviews cluster within 60 days of a funding announcement or Product Hunt launch (solicitation signal — check Crunchbase funding date vs. G2 review date histogram).
+7. NEVER present a "WHERE WE WIN" list without a matching "WHERE WE LOSE / NOT YET" list of equal candor and equal length.
+8. Flag loudly when the competitor's stated moat is a commodity (e.g., "best-in-class AI" via OpenAI/Anthropic API) vs. a structural differentiator (e.g., proprietary training data, exclusive distribution channel, regulatory certification that requires years to obtain).
+9. All pricing figures carry the exact date observed; SaaS pricing changes without notice and stale data corrupts live deal prep.
+10. The output is a battlecard for a senior sales or product strategist — not a summary for a general audience. Density over polish; omit anything that doesn't change a decision.
+
+═══ PHASE A — TARGET SCOPING ═══
+
+A1. Define the teardown target precisely before collecting any evidence:
+    - Competitor legal name + primary product name (they often differ; e.g., "Anthropic" sells "Claude")
+    - The specific product line or tier being analyzed (enterprise flagship? self-serve PLG tier? a vertical add-on?)
+    - Our product context: which Theron surface or SKU will this battlecard defend or attack with?
+    - Tear-down mode: DEFENSIVE (they are winning deals we should be winning) or OFFENSIVE (we are targeting their installed base)?
+    - Time horizon: is this for an imminent deal (next 30 days) or strategic roadmap input (next 12 months)? This changes what evidence to prioritize.
+
+A2. Identify primary evidence sources to collect in Phase B — do not collect yet, just list them:
+    - Marketing site: /, /pricing, /customers, /enterprise, /security, /blog, /changelog or /releases
+    - LinkedIn: company page (headcount, hiring velocity, department mix), active job postings
+    - G2 / Capterra / TrustRadius: filter to last 12 months; pull 1-3 star reviews (pain = our wedge) and 4-5 star reviews (what users love = their real moat)
+    - Crunchbase / PitchBook / SEC EDGAR: funding stage, investors, disclosed ARR or revenue
+    - Twitter/X, Hacker News ("Ask HN: who uses [competitor]?"), Reddit: unguarded user sentiment
+    - GitHub: public repos reveal architecture choices, what they build vs. what they buy, and contributor velocity
+    - Job postings: engineering roles reveal infra stack and model strategy; sales roles reveal ICP and deal motion; ML/AI roles reveal whether they are building proprietary models or wrapping APIs
+    - Podcast appearances or conference talks by founders or executives: the language they use off-script is often more honest than their marketing copy
+
+═══ PHASE B — EVIDENCE COLLECTION ═══
+
+B1. Pricing and Packaging — WebFetch /pricing on the date of analysis; record:
+    - All tier names, prices, billing periods, and seat definitions
+    - What is gated at each tier boundary: feature gates, usage caps, API access, SSO, audit logs, SLA, support tier
+    - Whether pricing is fully public or "contact sales" for any tier (hidden pricing above a threshold = enterprise-motion signal, not a prestige signal)
+    - Any usage-based components: per-seat vs. per-call vs. per-output-token vs. hybrid
+    - Free tier or trial structure (time-limited vs. usage-limited vs. feature-limited — each signals a different GTM motion)
+    - Date observed: required field, not optional
+
+B2. Positioning — collect verbatim from their homepage hero, About page, and recent paid ads:
+    - To find paid ads: search Meta Ad Library at facebook.com/ads/library for their brand name; search Google Ads Transparency Center; search "[competitor name] ad" on Twitter/X
+    - Primary headline: the one-sentence claim above the fold on their homepage
+    - Secondary positioning: the paragraph or bullet list under the headline
+    - Named ICP in copy: specific job titles, company sizes, or verticals called out
+    - Key proof points cited: customer logos, benchmark claims, compliance certifications, analyst recognitions
+    - Emotional hook: is the lead emotion speed, safety, cost reduction, autonomy, or trust?
+
+B3. Product capabilities — do NOT rely on their marketing feature list; cross-reference with:
+    - Their API or developer docs: what endpoints actually exist vs. what is described as "coming soon"
+    - Changelog or "What's New" page: look for /changelog, /releases, /updates, or their GitHub releases tab
+    - 1-3 star G2 reviews mentioning missing features (signal: "I wish it could…" or "it still can't…")
+    - Job postings describing features as "building" or "launching Q[X]" (not yet shipped)
+    - Open-source repos: reveals which components they build vs. which they wrap (a heavy langchain or litellm dependency means their AI layer is thinner than marketed)
+
+B4. GTM motion — infer from observable signals, not self-description:
+    - Sales page CTA: self-serve checkout card = PLG; "book a demo" as the only CTA above free = SLG
+    - LinkedIn hiring mix: SDR/AE ratio, presence of Solutions Engineers and Implementation Managers, CS headcount relative to sales headcount
+    - Content strategy: high-volume SEO blog = inbound/PLG; ROI calculators + compliance whitepapers + case studies with named CFO quotes = enterprise
+    - Partner ecosystem page: reseller/channel motion? marketplace listing (AWS Marketplace, Salesforce AppExchange)? OEM integrations?
+    - Event sponsorship: developer conferences = developer-led; enterprise IT events (Gartner Summit, RSA) = CISO/IT buyer; consumer channels = B2C or prosumer
+
+B5. Funding and burn signals — collect from Crunchbase + press:
+    - Total raised, last round size and date, lead investors and their typical portfolio profile
+    - Disclosed ARR or revenue: label source and date
+    - Headcount trend: LinkedIn "employees" count over the last 6-12 months — fast growth post-raise = burning capital to acquire; flat or declining post-Series-B = efficiency mode or growth plateau
+    - Any layoffs, pivots, or C-suite changes in the last 18 months: these are instability signals that create buying uncertainty in their customer base — a wedge opportunity
+
+═══ PHASE C — ANALYSIS: POSITIONING AND ICP ═══
+
+C1. Decode their actual ICP — infer from actions, not stated intentions:
+    - Which customer logos they lead with: company size, industry, geographic region
+    - Job titles named in copy and case studies (the title that appears in a hero quote is usually their champion persona)
+    - The pain points they lead with: operational efficiency, compliance/audit, cost reduction, speed, or competitive advantage
+    - The integration partners they highlight: Salesforce/HubSpot = revenue/GTM buyers; Slack/Notion/Linear = SMB/PLG; AWS Marketplace/Azure Marketplace = IT buyer; SOC 2/ISO 27001 badge placement = security-sensitive enterprise
+    - Their lowest paid tier's price point and its specific feature unlock: reveals the minimum viable buyer they want to land
+
+C2. Map their positioning to one of four archetypes and note if they are caught between two (bifurcation between archetypes = a weakness we can exploit with a cleaner story):
+    - AUTOMATION PLATFORM: "replaces headcount / automates workflows end-to-end"
+    - INTELLIGENCE LAYER: "makes your existing tools smarter / decision support without replacing them"
+    - TRUST INFRASTRUCTURE: "makes AI outputs auditable, compliant, or safe for regulated use"
+    - PERSONALIZED ASSISTANT: "learns your domain, your style, your workflows — forms around you"
+
+C3. Identify their narrative SEAM — the specific gap between what they claim and what their product actually delivers:
+    This is our primary attack surface. Examples of seams:
+    - Claiming "AI you can trust" when their verifier is their own model (self-referential trust = not trust)
+    - Claiming "enterprise-grade" while lacking SSO, audit logs, or a data processing agreement on their pricing page
+    - Claiming "understands your domain" when their base is a generic API wrapper with a system prompt
+    - Claiming "proprietary AI" while their changelog shows only prompt engineering and UI changes, and their ML job postings require "experience with OpenAI API"
+    A seam is where their marketing runs ahead of their product — it is where a well-prepared buyer will catch them, and where we position our alternative.
+
+═══ PHASE D — ANALYSIS: PRODUCT STRENGTHS AND GAPS ═══
+
+D1. Catalog genuine product strengths — only list items with supporting evidence:
+    Format: [Strength] → [Evidence source and date] → [Why users value it, in their words if possible]
+    Do not list "clean UI" or "responsive support" without a quote or a review count and rating that substantiates the claim.
+
+D2. Catalog verified product gaps — only list items with supporting evidence:
+    Format: [Gap] → [Evidence source and date] → [User pain, quoted or closely paraphrased]
+    Priority-sort by: (1) frequency of mention across multiple independent reviews, (2) alignment with our current shipped strengths.
+
+D3. Rate their execution velocity from their changelog:
+    - Source: /changelog, /releases, GitHub releases, or Product Hunt activity — specify which
+    - Count major capability releases vs. minor bug fixes in the last 12 months
+    - Identify any category where they ship multiple releases per quarter (signal: they believe it is core to their moat)
+    - Identify any category with no changelog activity in 6+ months (signal: deliberately deprioritized, stuck, or that roadmap item was dropped after a failed bet)
+    - Compare their shipping cadence to their fundraise date — post-raise slowdown is a culture or architecture signal
+
+D4. Assess their AI substrate honesty — this is the highest-leverage analysis dimension for an AI competitor:
+    - Do they name their underlying model? If they do not, it is almost certainly an API wrapper; that is fair game to surface with a buyer.
+    - Do they claim proprietary training or fine-tuning? If yes: is there a model card, an independent benchmark report, or a published eval methodology? A claim without a methodology is a marketing claim, not a product claim.
+    - Is their entire "AI" feature set reproducible by a competent prompt engineer with OpenAI or Anthropic API access and two weeks of work? If yes, their AI moat is commodity risk — the next OpenAI model release may erase it.
+    - Do they disclose what happens to customer data used for inference? Absence of a data processing addendum at the self-serve tier is an enterprise sales blocker we can weaponize.
+
+═══ PHASE E — ANALYSIS: MOAT ASSESSMENT ═══
+
+E1. Evaluate their moat against the four durable moat types; label each as REAL, FRAGILE, or ABSENT with specific supporting evidence:
+    - DATA NETWORK EFFECT: does using their product generate data that improves the product for other users? This requires a proprietary behavioral data loop — most AI SaaS products do not have this even when they claim it. ABSENT unless they can point to a specific mechanism.
+    - SWITCHING COST: how much workflow, integration, institutional knowledge, or reformatting work would a customer lose by leaving? Estimate in hours or dollars where possible. High switching cost = data exports are painful, or their output format is embedded in downstream systems.
+    - DISTRIBUTION LOCK-IN: are they embedded inside a mandatory workflow the buyer cannot remove — e.g., native to VS Code, inside a Salesforce workflow, inside a compliance audit trail a regulator touches?
+    - PROPRIETARY SUBSTRATE: do they own their model weights, their training pipeline, or a corpus that cannot be replicated with money alone? An exclusive data licensing deal or a proprietary synthetic data pipeline counts; "we fine-tune on OpenAI" does not.
+
+E2. Identify their most FRAGILE claimed advantage — the one that collapses if:
+    - OpenAI, Anthropic, or Google releases the same capability natively into their base model or API
+    - A well-funded open-source project (Llama, Mistral, Qwen, DeepSeek) delivers equivalent quality at zero marginal cost
+    - Their primary API provider changes pricing, terms of service, or deprecates the specific model version they depend on
+
+E3. Identify their stickiest genuine advantage — the one it would be strategically foolish to compete with head-on. Note explicitly what it would cost us in time and capital to close this gap, and whether it is worth attempting.
+
+═══ PHASE F — WIN / LOSE MAP ═══
+
+F1. WHERE WE WIN — list only dimensions where we have a durable, evidence-backed advantage today:
+    Format: [Dimension] | [Our position — specific, not "we are better"] | [Their gap — with evidence source] | [Evidence for our claim]
+    Do not list a dimension where our advantage is theoretical, on the roadmap, or unshipped.
+
+F2. WHERE WE LOSE / NOT YET — list with the same rigor and equal number of entries as F1:
+    Format: [Dimension] | [Their strength — with evidence] | [Our gap — honest assessment] | [What closing this gap requires — time, capital, strategic choice]
+    Label each gap with one of:
+    - STRATEGIC CHOICE: we will not close this because it conflicts with our position — explain why our position is correct
+    - ROADMAP: we will close this; specify by when and what ships
+    - REAL RISK: they may lock us out if we do not move within [timeframe]
+
+F3. DEAL SCENARIO TABLE — for the three most common deal types we encounter against this competitor:
+    | Deal type        | Buyer's primary criterion | We win if...                        | We lose if...                        |
+    |------------------|--------------------------|-------------------------------------|--------------------------------------|
+    | [e.g., mid-mkt]  | [e.g., time-to-value]    | [specific condition, not "we're better"] | [specific condition]            |
+    | [e.g., ENT]      | [e.g., compliance audit] | [specific condition]                | [specific condition]                 |
+    | [e.g., PLG/self-serve] | [e.g., price]      | [specific condition]                | [specific condition]                 |
+
+═══ PHASE G — WEDGE SELECTION ═══
+
+G1. Define THE single recommended attack vector — one paragraph, structured with these five labeled elements:
+    TARGET BUYER: [specific title + company profile + the trigger event that puts them in market now]
+    PAIN WE NAME: [the exact language from their 1-3 star reviews, job-post pain signals, or forum complaints — not our paraphrase of their pain]
+    OUR PROOF: [what we can demonstrate in a 30-minute meeting that they cannot replicate — must be something we can show, not describe]
+    THEIR SEAM WE EXPOSE: [the specific claim vs. reality gap from C3, surfaced as a buyer-facing question rather than an attack: "How do you verify that the AI's output is correct if the verifier is the same model that produced it?"]
+    ONE-LINE POSITIONING AGAINST THEM: [the exact sentence a sales rep uses when the prospect says "we're also looking at [competitor]" — should name the category we own, not attack their brand]
+
+G2. Secondary wedges (max 2) — use the same five-element structure as G1 at lower confidence; label each element's confidence as HIGH / MEDIUM / LOW and note what evidence would upgrade it:
+    TARGET BUYER: [...]  [confidence: X]
+    PAIN WE NAME: [...]  [confidence: X]
+    OUR PROOF: [...]  [confidence: X]
+    THEIR SEAM WE EXPOSE: [...]  [confidence: X]
+    ONE-LINE POSITIONING: [...]  [confidence: X]
+
+G3. ANTI-PATTERNS TO AVOID in this specific competitive situation — at least 2, specific to this competitor:
+    Generic anti-patterns (e.g., "don't be arrogant") are not acceptable here. These must be specific to competing with this company: e.g., "do not compete on price — they have 3x our runway and will match any discount we offer"; "do not lead with benchmark comparisons — their developer community will publicly dispute any benchmark we publish without a live demo to anchor it"; "do not attack their enterprise sales motion — their AEs are senior and will outmaneuver us on legal/security review every time; go around them to the technical champion."
+
+═══ PHASE H — BATTLECARD OUTPUT ═══
+
+H1. Deliver a structured battlecard with these exact sections, in this order:
+
+    COMPETITOR: [legal name — product name]
+    SNAPSHOT DATE: [date — re-verify before any live deal]
+
+    ONE-LINER: [one sentence — what they are, who they are for, and the category they claim]
+
+    ICP:
+    - [Buyer persona 1: title, company profile, trigger]
+    - [Buyer persona 2]
+    - [Buyer persona 3 if applicable]
+
+    PRICING SNAPSHOT: [date observed]
+    - [Tier name]: $[price]/[period] — [key feature gate at this tier]
+    - [Tier name]: $[price]/[period] — [key feature gate]
+    - [Enterprise]: [public price or "contact sales"] — [what triggers the enterprise conversation]
+
+    THEIR REAL MOAT: [1-2 sentences — the thing that is genuinely hard to beat and why; be honest]
+
+    THEIR SEAM: [1-2 sentences — the specific gap between their biggest claim and what their product actually delivers]
+
+    WHERE WE WIN:
+    - [Dimension] — [evidence-backed, shipped today]
+    - [Dimension] — [evidence-backed, shipped today]
+
+    WHERE WE LOSE / NOT YET:
+    - [Dimension] — [their strength; labeled STRATEGIC CHOICE / ROADMAP / REAL RISK]
+    - [Dimension]
+
+    RECOMMENDED WEDGE: [G1 condensed to 4-5 lines; keep all five labeled elements]
+
+    TALK TRACK — OBJECTION HANDLERS:
+    Format for each: Prospect says: "[verbatim or close paraphrase of the objection]" → We say: "[the response — one to three sentences, leads with agreement or acknowledgment, pivots to our structural advantage, never attacks their brand by name]"
+    - Prospect says: "[most common objection]" → We say: "[response]"
+    - Prospect says: "[second most common objection]" → We say: "[response]"
+    - Prospect says: "[third]" → We say: "[response]"
+    - Prospect says: "[fourth if applicable]" → We say: "[response]"
+
+    OPEN QUESTIONS: [what we still do not know that would materially change this analysis — list as questions, not statements; include what evidence source would answer each]
+
+H2. After the battlecard, state: the single assumption in this entire analysis most likely to be wrong, why it might be wrong, and what specific evidence would correct it.
+
+H3. Date-stamp the entire output: "Competitive snapshot as of [DATE]. Re-verify pricing, changelog, and headcount before any live deal. This battlecard expires in 90 days or at their next funding announcement, whichever comes first."

package/skills/component-spec.md

@@ -0,0 +1,121 @@
+---
+name: component-spec
+description: Produce a complete, build-ready UI component specification covering anatomy, prop/variant matrix, every interaction and data state, design tokens (color/space/type/motion/dark-mode), full accessibility contract (ARIA roles, keyboard, focus), responsive rules, automation hooks, breaking-change policy, and do/don't usage — output is the single source of truth a designer and engineer both build from without a meeting.
+allowed-tools: Read, Write
+---
+
+═══ HARD RULES ═══
+1. Every prop must carry: name · type · required/optional · default · enumerated values (no open-ended "string" when a union is correct).
+2. Never invent token names — derive them from the consuming system's actual token scale; flag UNKNOWN if tokens are unresolved.
+3. State matrix must be exhaustive: enumerate every combination of data state × interaction state before writing prose.
+4. Accessibility contract is non-negotiable — every interactive element needs role, aria-label strategy, keyboard trigger, and focus-visible treatment.
+5. Do/Don't examples must be component-specific; reject any example that could apply to a generic element.
+6. Motion tokens (duration, easing) must appear wherever a state transition is visible — "no animation" is a valid explicit value, and every motion rule must declare whether it respects prefers-reduced-motion.
+7. A spec is DONE only when a senior engineer could build the component to pixel-fidelity without asking a follow-up question.
+8. Every interactive element must expose a stable data-testid or equivalent automation hook — document its naming convention and ownership (component-owned vs. caller-provided).
+9. Any prop change that alters the public API (rename, type narrowing, removal) is a BREAKING CHANGE and must be flagged before spec sign-off; the spec must record the semantic version bump required.
+10. This spec covers web surfaces only (desktop/tablet/mobile browser). Native (iOS/Android) and email/print are explicitly OUT OF SCOPE unless the consuming system opts them in with a separate native-contract section.
+
+═══ PHASE A — ORIENT: NAME, SCOPE, AND ROLE ═══
+A1. State the component's canonical name in PascalCase and its package import path (e.g., `import { Button } from '@acme/ui/button'`).
+A2. Write one sentence: what user need does this component solve, and what it intentionally does NOT do (e.g., "handles label + icon button affordance; does NOT handle menu-trigger or link navigation — use IconButton or LinkButton for those").
+A3. Identify the component's layer in the design system hierarchy:
+    - primitive — no external component dependencies (e.g., Token, Icon)
+    - composite — composes two or more primitives (e.g., InputField = Input + Label + ErrorText)
+    - pattern — composes composites to express a recurring UX workflow (e.g., SearchBar)
+    - page-section — full layout region, not reusable at component granularity
+A4. List every direct child component this component composes — note which are internal (same package) and which are external (peer dependency). If an external component's version is pinned, record it.
+A5. Record the consuming surfaces in scope for this spec: web-desktop · web-tablet · web-mobile. State any responsive behavior that differs by surface.
+
+═══ PHASE B — ANATOMY ═══
+B1. Produce a named-parts diagram in ASCII or structured list — every visual region gets a part name (root, trigger, label, icon-leading, icon-trailing, helper-text, error-text, badge, overlay, etc.).
+B2. For each part:
+    - Semantic HTML element (e.g., `<button>`, `<span>`, `<div role="status">`)
+    - Whether it is always-rendered or conditionally-rendered (and the condition)
+    - The CSS class slot it exposes for external override (e.g., `.btn__label`) and the data-attribute for state querying (e.g., `data-state="loading"`)
+B3. Call out which parts are SLOTS (caller-provided content via children/slot prop) vs. OWNED (component-controlled). Slots that accept arbitrary JSX must document any rendering constraints (e.g., "only one child, must be an inline element").
+B4. Assign a stable data-testid to each part that an automated test may need to target. Use a hierarchical naming convention: `{component}-{part}` (e.g., `button-label`, `button-icon-leading`). Mark which are component-owned vs. caller-overridable.
+
+═══ PHASE C — PROPS AND VARIANTS ═══
+C1. Build a full prop table with columns: Prop | Type | Required | Default | Notes.
+C2. Define the variant axis first (e.g., `variant: 'primary' | 'secondary' | 'ghost' | 'danger'`), then size, then boolean modifiers (disabled, loading, fullWidth, etc.). Every value in a union must appear — no "and others" shortcuts.
+C3. State which prop combinations are INVALID and what the component does on receipt: warn-to-console + graceful fallback, or hard error with thrown exception. Document the exact console.warn message text so engineers can search for it.
+C4. List every compound variant: style overrides that apply only when two or more props intersect (e.g., `size="sm" + loading=true` collapses label to visually-hidden; `variant="ghost" + disabled=true` removes border, not just reduces opacity).
+C5. Enumerate every data state and describe how props map to each:
+    - empty / blank
+    - loading / pending
+    - populated / success
+    - error / invalid
+    - warning
+    - read-only
+    - disabled
+    Add any component-specific states not listed here (e.g., indeterminate for checkboxes, dragging for sortable items).
+
+═══ PHASE D — INTERACTION AND BEHAVIOR STATES ═══
+D1. List all interaction states the component must render: default · hover · focus-visible · focus-within · active/pressed · dragging · selected · indeterminate (where applicable).
+D2. For EVERY state: describe the exact visual delta using token names only — no raw hex, no raw px. Example: "background changes from --color-action-bg to --color-action-bg-hover; border-color unchanged."
+D3. For each state transition: property animated · duration token · easing token · whether the transition is suppressed under prefers-reduced-motion (state "suppressed" or "retained — motion is meaningful").
+D4. Define the pointer/touch target area explicitly:
+    - Minimum 44×44 px per WCAG 2.5.5 and Apple HIG.
+    - If the visual hit area is smaller than 44×44 px, describe the invisible touch-target expansion technique used (padding, ::before overlay, etc.).
+D5. Specify any non-default pointer behaviors if applicable: long-press (with delay token), right-click / context-menu, pointer-capture during drag. If none apply, write "none."
+D6. For composite components: describe internal event routing. State explicitly which child events propagate to the root and which are stopped (e.g., "click on icon-trailing fires onClear; does NOT propagate to the root onClick").
+
+═══ PHASE E — DESIGN TOKENS ═══
+E1. Group tokens by category: Color · Space · Typography · Border · Shadow · Motion.
+E2. Color — for every part × every interaction/data state, map to a semantic token for each property:
+    - background → --color-{semantic}-bg[-{state}]
+    - text → --color-{semantic}-text[-{state}]
+    - border → --color-{semantic}-border[-{state}]
+    - focus ring (outline) → --color-focus-ring
+    - icon fill → --color-{semantic}-icon[-{state}]
+    Use semantic tokens (e.g., --color-action-bg-hover) not primitive tokens (e.g., --blue-500). If the system has no semantic layer yet, note this and use the primitive token with a FIXME comment.
+E3. Dark mode — for every semantic token used, state whether the system's dark-mode token contract swaps it automatically (via CSS color-scheme / data-theme attribute) or whether the component must apply a dark-specific token override. Flag any token that has no dark-mode equivalent as UNKNOWN-DARK.
+E4. Space — for each size variant: block padding, inline padding, gap between internal parts, icon size. State whether the component is margin-agnostic (preferred — the component sets no external margin).
+E5. Typography — per text part (label, helper-text, error-text, placeholder): font-family token · size token · line-height token · font-weight token.
+E6. Motion — duration token + easing token for each transition identified in Phase D.
+E7. Flag every token that is UNKNOWN (not yet defined in the system). Do not silently substitute a raw value; a spec with raw values is not shippable.
+
+═══ PHASE F — ACCESSIBILITY CONTRACT ═══
+F1. State the ARIA role of the root element and every interactive child. Where the role is implicit from the HTML element, write both (e.g., `<button>` → implicit role="button"; do not add an explicit role attribute).
+F2. Define the aria-label / aria-labelledby / aria-describedby strategy:
+    - When is each attribute required vs. optional?
+    - What is the fallback if the consumer omits a required label? (The component must warn in development; document the exact warning.)
+F3. List every aria-* live state that applies: aria-disabled · aria-expanded · aria-selected · aria-checked · aria-invalid · aria-busy · aria-pressed · aria-haspopup. For each: what prop drives it, and what is the value in each data state.
+F4. Keyboard contract — table with columns: Key | Condition | Action | Focus destination after.
+    Must include at minimum: Enter, Space, Escape, Tab, Shift+Tab. Add arrow keys, Home, End if the component implements a composite widget pattern (listbox, menu, tabs, grid).
+F5. Focus management:
+    - Does the component trap focus (modal/dialog pattern)?
+    - Does it restore focus to a previous element on close, and under what condition?
+    - Does it programmatically move focus (e.g., after async action completes)? If so, what is the timing (synchronous, or after a microtask/frame)?
+F6. Color contrast — for each distinct text-on-background combination in the component: name the token pair and the required WCAG 2.1 ratio (4.5:1 for normal text, 3:1 for large text and UI controls). Do not compute the ratio here — mark each as MUST VERIFY against live resolved token values before sign-off.
+F7. Screen reader announcement — describe the complete VoiceOver/NVDA read-out for the most complex interaction path through this component (e.g., for a password input: "Password, secure text field, 8 characters, required, You must include a number, invalid"). Include the role, name, state, and any live-region announcements triggered by async feedback.
+
+═══ PHASE G — RESPONSIVE RULES ═══
+G1. Define the breakpoint vocabulary using the system's canonical breakpoint tokens (e.g., sm / md / lg / xl) — never raw px values in this section.
+G2. For each breakpoint where layout changes: list every change explicitly — stack vs. inline, full-width collapse, icon-only mode, truncation behavior. State prop overrides that are forced by the component at a breakpoint (e.g., "below sm, fullWidth is forced true regardless of prop").
+G3. State whether the component uses intrinsic sizing (min-content / fit-content) or extrinsic sizing (parent-controlled width) as its default. Document how each size variant interacts with a constrained container.
+G4. Call out any pointer-type behavior changes: behaviors available only on hover (e.g., tooltip reveal) must have a touch-equivalent disclosure path.
+
+═══ PHASE H — DO / DON'T USAGE GUIDE ═══
+H1. List 4–6 DO examples specific to THIS component's domain. Each must:
+    - Show the correct prop or composition pattern.
+    - Explain the user or accessibility benefit.
+    - Be wrong or suboptimal without following the rule.
+H2. List 4–6 DON'T examples. Each must:
+    - Identify the anti-pattern and the exact prop combination that creates it.
+    - State the harm: accessibility regression, visual breakage, semantic mismatch, or performance cost.
+H3. Adjacent components — for each named alternative in the system, write one line: "Use [X], not [this component], when [specific condition]." Do not name components that do not exist in the consuming system.
+H4. Third-party integration constraints — if this component internally wraps or conflicts with any third-party library that consumers are likely to also use (e.g., a tooltip library, a focus-trap library, a form library), document the constraint as a pattern: "Do not add an external [tooltip / focus-trap / form-field wrapper] around this component — doing so breaks [specific ARIA relationship / event contract / focus behavior] because [reason]." Name the third-party library only if it is a confirmed peer dependency of this design system.
+
+═══ PHASE I — OPEN QUESTIONS, VERSIONING, AND SIGN-OFF ═══
+I1. Breaking-change register — list any prop rename, type narrowing, removal, or behavior change relative to the previous version of this component. For each: record the semver bump required (major / minor / patch) and the migration path (codemod available? manual change needed?).
+I2. Deferred decisions — for every decision that is not yet resolved: state the question, the owner (name or role), and the target date. A spec with unresolved decisions must not be marked ready for engineering.
+I3. Unknown tokens — list every token flagged UNKNOWN or UNKNOWN-DARK from Phase E. Do not ship a spec with silent placeholder values.
+I4. Record: spec version · author · last-updated date · design file link (Figma frame or equivalent).
+I5. Sign-off requirement — all three reviews must be explicitly recorded before this spec is considered shippable:
+    - Design review ✓ — [name, date]
+    - Engineering review ✓ — [name, date]
+    - Accessibility review ✓ — [name, date]
+
+KEY PRINCIPLE: A component spec is not documentation after the fact — it is the contract that makes design and engineering the same conversation before a single line of code is written. Every UNKNOWN is a future meeting; eliminate them here.