OpenParable
Skip to content
← Back to skills

Research Component

Design
research-component

Research Component is an Agent Skill for design published in the inkline/inkline repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Phase 1 of building an Inkline component — design the API. Survey the WAI-ARIA pattern and prior art, then write a complete component spec (props, slots, events, variants, accessibility, styling plan) to .context/ for sign-off before any code. Use when starting a new component or redesigning an existing one's API.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/inkline/inkline/blob/HEAD/.claude/skills/research-component/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/research-component, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Component research — design the API before any code

The goal of this phase is a spec good enough that implementation is mechanical. A great component is decided here: the right anatomy, the best prop names, the exact accessibility contract. Produce a written spec, get it signed off, then hand it to implement-component.

Read first

  1. .claude/skills/create-component/reference/conventions.md — naming philosophy, the prop/variant vocabulary, the a11y baseline. The prop-naming rules there are the bar.
  2. The nearest exemplar to what you're building (badge = simplest, button = stateful, input = multi-part family) under ui/components/src/components/.

Steps

  1. Pin the accessibility pattern. Identify the WAI-ARIA Authoring Practices (APG) pattern for this widget (button, dialog, combobox, tabs, switch, tooltip, …). If unsure or it's non-trivial, WebSearch / WebFetch the APG page and extract: the required role(s), the states/properties, and the full keyboard map. Prefer a native element (<button>, <input>, <dialog>, <a href>) — note which native element gives you the pattern for free.

  2. Survey prior art for the API surface. Look at how mature libraries name things for this component — Radix UI, Ark UI, Headless UI / Reka, MUI — and the Inkline v0 implementation in .old/ (read-only reference; grep it for the component name). Capture the prop/variant names worth adopting and explicitly note what you reject and why. Goal: idiomatic, unsurprising names a senior engineer wouldn't second-guess.

  3. Decide the anatomy. One part or a family? List the headless parts and the single styled composition that ties them together (Input is the model: shell + control + prefix + suffix → one IInput). Each structural part = one I<Name>*Base.

  4. Design the props. Apply the naming philosophy from conventions.md literally:

    • positive boolean state adjectives, no is/has prefix;
    • the color / variant / size trio only with the values the recipe supports;
    • native attribute names mirrored exactly;
    • a label + default-slot fallback for simple content, named slots for structured content;
    • two-way state as a defineModel, semantic unprefixed events. The zero-config case should be the common case. Give every prop a one-line rationale.
  5. Check the styling source. @styleframe/theme ships a broad recipe catalog (Accordion, Alert, Avatar, Badge, Breadcrumb, Calendar, Callout, Card, …), so for most components a recipe already exists and you reuse it. Confirm whether use<Name>Recipe is exported:

    grep -rhoE "use[A-Z][A-Za-z]+Recipe\b" node_modules/.pnpm/@styleframe+theme@*/node_modules/@styleframe/theme/ | sort -u | grep -i "<name>"
    

    Record the answer — it decides the implement phase's styling branch: reuse use<Name>Recipe(s) if it exists (the common case), else author styles locally in .styleframe.ts. If the grep is inconclusive, default to "author locally" (safe) and note it for sign-off.

  6. Write the spec to .context/component-<name>-spec.md using the template below. Fill every section. Where a decision is genuinely open, list it under "Open questions" rather than guessing.

  7. Gate. Present the spec's headline decisions (anatomy, prop table, a11y contract, styling branch) and ask for sign-off. Use AskUserQuestion only for genuine forks; otherwise state assumptions and proceed. Do not start implementing from this skill.

Spec template

# Component spec: I<Name>

## Purpose

<one paragraph: what it is, when a consumer reaches for it>

## Prior art

- APG pattern: <name + key requirements>
- Libraries reviewed: <takeaways adopted / rejected, with reasons>

## Anatomy

<headless parts + the single styled composition; ASCII tree>

## Props

| Prop | Type | Default | Required | Rationale |
| ---- | ---- | ------- | -------- | --------- |

<every prop, including the color/variant/size trio if styled>

## Slots

| Slot | Purpose | Gated by hasSlot? |

## Events & models

- models: defineModel("<name>") → …
- emits: <event>: [payload] — when it fires

## Variants

- color / variant / size: <only the supported value sets>
- state: disabled / loading / invalid / … as applicable

## Accessibility contract

- Native element / role:
- APG states & properties:
- Keyboard map: <key → action>
- Focus management:
- Accessible name / labelling:

## Styling plan

- @styleframe/theme exports use<Name>Recipe? <yes/no — checked via grep>
- Plan: <reuse theme recipe | author locally: selectors/recipe axes + :empty rules for gated addons>

## Open questions

<anything needing the user's call>

Exit criteria

.context/component-<name>-spec.md exists, every section filled, styling branch decided, and the user has signed off on the API. The spec is the contract the next four phases build against.