.agents/skills/shade-input-surface-recipe/SKILL.md
inputSurface recipeForm controls share one visual rule: border, background, radius, transition, focus ring, invalid state. That rule lives in inputSurface (apps/shade/src/components/ui/input-surface.ts) and is used by Input, Textarea, InputGroup, and the Select trigger. Don't duplicate the chrome — compose the recipe.
import {inputSurface, inputSurfaceClasses} from '@/components/ui/input-surface';
import {cn} from '@/lib/utils';
inputSurface('self') — directly on the focusable elementUse on <input>, <textarea>, or any element that itself receives focus.
<input
className={cn(
inputSurface('self'),
'flex h-9 w-full px-3 py-1 text-control placeholder:text-muted-foreground',
className
)}
{...props}
/>
Covers: base chrome + focus-visible: ring + aria-[invalid=true] styling + disabled: opacity.
inputSurface('within') — on a wrapper containing a focusable childUse when the styled element is the wrapper (e.g. InputGroup) and focus state should react to any focusable descendant via :has().
<div className={cn(
inputSurface('within'),
'flex h-9 items-center gap-2 px-3',
className
)}>
<Icon />
<input className="bg-transparent outline-hidden focus:outline-hidden" />
</div>
Covers: base chrome + has-[:focus-visible]: ring + has-[[aria-invalid=true]]: styling. (No disabled atom — wrappers don't get a disabled HTML attribute.)
When 'within' is too broad (e.g. a wrapper with multiple focusables but only one should drive chrome), compose atoms manually so Tailwind's JIT can statically detect the class string:
import {inputSurfaceClasses} from '@/components/ui/input-surface';
<div className={cn(
inputSurfaceClasses.base,
inputSurfaceClasses.invalidWithin,
// Literal class string — Tailwind needs to see it as text
'has-[[data-slot=control]:focus-visible]:border-focus-ring',
'has-[[data-slot=control]:focus-visible]:ring-2',
'has-[[data-slot=control]:focus-visible]:ring-focus-ring/25'
)} />
Available atoms:
inputSurfaceClasses.base — border, background, radius, transitioninputSurfaceClasses.focusSelf — focus chrome for self modeinputSurfaceClasses.focusWithin — focus chrome for within modeinputSurfaceClasses.invalidSelf — aria-[invalid=true] styling on selfinputSurfaceClasses.invalidWithin — aria-[invalid=true] styling on a descendantinputSurfaceClasses.disabledSelf — disabled styling for self mode| Recipe owns | You add |
|---|---|
Border (border-control-border) | Height, padding |
Background (bg-surface-elevated, dark:bg-transparent) | Typography (text-control, text-sm) |
Radius (rounded-md) | Layout (flex, items-center) |
Transition (transition-colors) | Placeholder styling |
Focus ring (focus-visible:ring-focus-ring/25) | Component-specific tweaks |
Invalid state (aria-[invalid=true]:border-destructive) | Icons / slot positioning |
Disabled (disabled:opacity-50) — self only | — |
// BAD — rolling your own focus chrome on a form control
<input className="
rounded-md border border-input bg-background
focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring
aria-[invalid=true]:border-red-500
disabled:opacity-50
" />
// BAD — using inputSurface('within') on a self-focused element (over-broad)
<input className={cn(inputSurface('within'), 'h-9')} />
// BAD — non-literal class concatenation that Tailwind JIT can't see
const dyn = `has-[[data-slot=control]:focus-visible]:${ringColor}`;
apps/shade/src/components/ui/input-surface.ts — the JSDoc on inputSurface is canonical. Human docs: Storybook → Recipes / inputSurface.