# Fine-tune card
> A small inspector in which an agent adjusts a design’s layout, size, radius, opacity and type, and the reader can take over.
An inspector card for one design. While the agent works, its Adjust label shimmers; it picks a layout, counts each number to a new value and chooses a type from a menu, and the header turns to a green Edited. Every control works by hand too: drag a field’s name to scrub it, use the arrow keys or type the number, and each field you change keeps a blue tint so the edits read at a glance.
A React component by Bruno Delorence: https://brunodelorence.com/components/fine-tune-card. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: AI.
## Anatomy
1. **Card**: A 240 px inspector on a soft stage. Its name sits at the left of the header.
2. **Status**: The agent’s words, shimmering every 1.4 s while it works; a green Edited that pops in once anything has changed.
3. **Layout control**: Row, column or grid as a radio group. Arrow keys move the choice.
4. **Thumb**: The raised piece under the choice; it slides by a transform in 300 ms.
5. **Number field**: A number with its name as a handle. Once changed it keeps a blue tint and ring.
6. **Handle**: The field’s name is a slider: drag it sideways to scrub half a unit a pixel, or use the arrow keys, Shift for tens.
7. **Type select**: A button that opens a small menu upwards; it reads the placeholder until a type is picked.
## When to use
- An agent adjusting a design’s properties where the reader can watch each value change and take over at any moment.
- A handful of numbers and choices on one selected thing: layout, size, corner radius, opacity, a type.
- Precise tweaks by feel: dragging a field’s name scrubs its number, arrow keys step it, typing sets it.
- Showing at a glance what was changed: edited fields keep a blue tint and ring, and the header turns to Edited.
## When not to use
- A full inspector with dozens of properties in groups. Use a panel with collapsible sections.
- Values without a sensible range or step, such as names or free text. Use a form.
- An agent that must ask before it changes anything. Use an approval card that waits for an answer.
- Settings that apply to the whole app rather than one selected object. Use a settings page.
## Installation
Install it with the shadcn CLI, into components/fine-tune-card of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/fine-tune-card.json
```
Or copy all the source files below into one folder of your project. Either way it needs React 19 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { FineTuneCard, type FineTuneValues } from './fine-tune-card';
export function CardInspector({ onEdit }: { onEdit: (values: FineTuneValues) => void }) {
return (
);
}
```
## States
- **Untouched**: The starting values, and the agent’s words in the header. Their shimmer keeps running.
- **Agent writing**: The layout is set and the width is counting: its handle turns blue and the field takes the ring.
- **Type menu open**: The four numbers are done; the menu pops up from its corner with the highlight on a row.
- **Edited**: Every change in: the changed fields keep their ring and the header says Edited.
- **Changed by the reader**: One field edited by hand: only it is ringed, and the header turns to Edited at once.
- **Dark**: With `colorScheme="dark"`: a graphite stage, the card a step lighter.
## How it works
- Layout is a radio group drawn as a segmented control: one raised thumb, a third of the well wide, slides under the choice by a transform (300 ms on a soft ease-out) while the icons cross from grey to blue in 200 ms. The arrow keys move the choice.
- Each number is a field whose name is its handle, a slider in its own right. Dragging the name sideways scrubs the value at half a unit per pixel, with the pointer captured so the drag can leave the card; the arrows step by one, Shift by ten, Home and End go to the ends.
- The number itself is a text field that keeps only digits while typing, and commits on Enter or on leaving, clamped to the field’s range; Escape puts the value back.
- A field once changed keeps an accent tint and a 1 px accent ring, crossing in 200 ms, so the card shows what has been edited. The first change turns the header from the shimmering Adjust to a green Edited that pops in (250 ms, from 95 %).
- The shimmer is a gradient, accent to a lighter accent and back, twice the width of the words and clipped to them, running right to left every 1.4 s.
- Type is a listbox that opens upwards from its button, popping from its bottom right corner in 200 ms while the chevron turns over. A soft highlight glides to the row under the pointer or the focus by its top and height (220 ms), and fades when the pointer leaves. It closes on a pick, Escape or a press outside.
- While on screen and untouched, a demo plays the agent: it picks the grid layout, counts width, height, radius and opacity to new values one after another on an ease-in-out curve, the name of the field it writes lit in blue, opens the menu, walks the highlight down and picks a type, then marks the card Edited, waits three seconds and starts over. Its edits never reach onChange; any key or press hands the card to the reader.
- Every colour is a light-dark() token on the root, so the card follows the page’s color-scheme or the colorScheme prop. Shadows are written once with all their layers, those a scheme does not use being transparent: long soft lifts by day, short dark ones at night.
## API reference
- **title** (`string`, default `'Flavor card'`): The name of what is being inspected, in the header.
- **defaultValues** (`Partial`, default `{ layout: 'row', width: 324, height: 96, radius: 28, opacity: 100, type: null }`): Where the card starts, and where the demo returns to: layout (row, column or grid), width, height, radius, opacity and type.
- **defaultState** (`FineTuneState`): Opens the card mid-way: edited (the header reads the edited label), touched (the fields drawn as changed), busy (the field the agent is writing), open (the Type menu) and highlight (its lit row). Setting it turns the demo off.
- **onChange** (`(values: FineTuneValues) => void`): Called with every value after each change the reader makes.
- **typeOptions** (`string[]`, default `['Seasonal', 'Classic', 'Limited']`): The choices in the Type menu.
- **typePlaceholder** (`string`, default `'Select type'`): The Type button’s words before a choice.
- **demoValues** (`Partial`, default `{ layout: 'grid', width: 360, height: 120, radius: 16, opacity: 90, type: 'Limited' }`): What the demo agent sets.
- **agentLabel** (`string`, default `'Adjust'`): The header’s shimmering words while the agent works.
- **editedLabel** (`string`, default `'Edited'`): The header’s words once something has changed.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a demo agent adjusts the card by itself and starts over.
- **colorScheme** (`'light' | 'dark' | 'system'`): Its colours: light, dark, or the reader’s system setting. Without it the component follows the page’s color-scheme, which is light unless the page sets one.
- **className** (`string`): Extra class for the root.
## Accessibility
- The card is a section named by its heading. Layout is a radiogroup of three radio buttons named Row, Column and Grid, with one tab stop and the arrow keys to move.
- Each field’s name is a slider (aria-valuenow, min and max; Opacity also says its percent) that the arrows, Shift, Home and End move; its number is a text field named “W value” and so on, with the up and down arrows stepping too.
- Type is a button with aria-haspopup="listbox" and aria-expanded; its listbox of options with aria-selected opens on a press or the arrow keys, takes the focus to the chosen row, moves with the arrows, Home and End, and closes on Escape, giving the focus back.
- The first change the reader makes is announced politely (“Flavor card: edited”); the demo’s edits are not. Focus rings are visible on every control, the select ringing in the accent.
- Under reduced motion the shimmer stands still, the thumb, tints, menu and highlight change at once, and the demo never plays.
## Source
### fine-tune-card/fine-tune-card.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useEffect,
useId,
useLayoutEffect,
useRef,
useState,
type KeyboardEvent as ReactKeyboardEvent,
type PointerEvent as ReactPointerEvent,
} from 'react';
import { useAutoplay } from './use-autoplay';
import styles from './fine-tune-card.module.css';
/*
* Fine-tune card: a small inspector in which an agent adjusts a design's properties (its layout,
* size, corner radius, opacity and type), and the reader can take over at any time.
*
* - The header says what is going on: "Adjust", its words shimmering, while the agent works; a
* green "Edited" that pops in once something has changed.
* - Layout is a three-way segmented control; the raised thumb slides under the choice by a
* transform (300 ms, a soft ease-out) while the icons cross their colours.
* - Each number is a field with its name as a handle: drag the name sideways to scrub (half a
* unit per pixel), use the arrow keys on it (Shift for tens), or type in the number. A field
* once changed keeps a blue tint and ring, so the edits read at a glance.
* - Type is a small menu that opens upwards; a soft highlight glides between its rows.
* - While on screen and untouched, a demo plays the agent: it picks a layout, counts each number
* to a new value, opens the menu, hovers and picks a type, then marks the card edited, waits and
* starts over. Any real input hands the card to the reader.
* - defaultState opens it mid-way (fields changed, one being written, the menu open on a row,
* the header edited), for documentation and tests; it turns the demo off.
* - Light or dark: every colour is a light-dark() token in the CSS, so the scheme is the page's
* color-scheme, or the one the colorScheme prop sets.
*/
export type FineTuneLayout = 'row' | 'column' | 'grid';
export type FineTuneValues = {
layout: FineTuneLayout;
width: number;
height: number;
radius: number;
opacity: number;
/** The chosen type, or null before one is chosen. */
type: string | null;
};
export type FineTuneField = 'width' | 'height' | 'radius' | 'opacity';
type NumberKey = FineTuneField;
/** Where the card opens (defaultState): for documentation and tests. */
export type FineTuneState = {
/** The header says the edited label instead of the agent's. */
edited?: boolean;
/** The fields drawn as changed: a blue tint and ring. */
touched?: FineTuneField[];
/** The field the agent is writing: its handle in the accent. */
busy?: FineTuneField | null;
/** The Type menu open. */
open?: boolean;
/** The menu row under the highlight. */
highlight?: number | null;
};
const DEFAULTS: FineTuneValues = {
layout: 'row',
width: 324,
height: 96,
radius: 28,
opacity: 100,
type: null,
};
/** What the demo agent sets, in this order. */
const DEMO: FineTuneValues = {
layout: 'grid',
width: 360,
height: 120,
radius: 16,
opacity: 90,
type: 'Limited',
};
const TYPES = ['Seasonal', 'Classic', 'Limited'];
const FIELDS: { key: NumberKey; label: string; min: number; max: number; unit?: string }[] = [
{ key: 'width', label: 'W', min: 40, max: 999 },
{ key: 'height', label: 'H', min: 24, max: 999 },
{ key: 'radius', label: 'Radius', min: 0, max: 64 },
{ key: 'opacity', label: 'Opacity', min: 0, max: 100, unit: '%' },
];
const LAYOUTS: { value: FineTuneLayout; label: string }[] = [
{ value: 'row', label: 'Row' },
{ value: 'column', label: 'Column' },
{ value: 'grid', label: 'Grid' },
];
/** Each layout's icon. */
const ICONS: Record = {
row: styles.iconRow,
column: styles.iconColumn,
grid: styles.iconGrid,
};
/** Scrubbing: units per pixel the handle is dragged. */
const SCRUB = 0.5;
const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
/** The demo's counting curve: slow out, fast through the middle, slow in. */
const easeInOut = (t: number) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2);
/** Thrown into the demo's script when it is stopped. */
const STOP = Symbol('stop');
export function FineTuneCard({
title = 'Flavor card',
defaultValues,
demoValues,
typeOptions = TYPES,
typePlaceholder = 'Select type',
agentLabel = 'Adjust',
editedLabel = 'Edited',
onChange,
autoplay = true,
defaultState,
colorScheme,
className = '',
}: {
/** The name of what is being inspected, in the header. */
title?: string;
/** The values the card starts from (and the demo returns to). */
defaultValues?: Partial;
/** The values the demo agent sets. */
demoValues?: Partial;
/** The Type menu's choices. */
typeOptions?: string[];
typePlaceholder?: string;
/** The header's words while the agent works. */
agentLabel?: string;
/** The header's words once something has changed. */
editedLabel?: string;
/** Called with every value after each change the reader makes. */
onChange?: (values: FineTuneValues) => void;
/** While on screen and untouched, a demo agent adjusts the card by itself. */
autoplay?: boolean;
/** Opens the card in a given state, with the demo off. */
defaultState?: FineTuneState;
/** Light or dark colours, or the reader's ('system'); without it, the page's color-scheme. */
colorScheme?: 'light' | 'dark' | 'system';
className?: string;
}) {
const start: FineTuneValues = { ...DEFAULTS, ...defaultValues };
const target: FineTuneValues = { ...DEMO, ...demoValues };
const { ref: root, playing, take } = useAutoplay(6000);
const [values, setValues] = useState(start);
const [touched, setTouched] = useState>>(() =>
Object.fromEntries((defaultState?.touched ?? []).map((key) => [key, true])),
);
const [edited, setEdited] = useState(defaultState?.edited ?? false);
/** Bumped when the header returns to the agent's words, so they pop in again. */
const [round, setRound] = useState(0);
/** The field the demo agent is writing. */
const [busy, setBusy] = useState(defaultState?.busy ?? null);
const [drafts, setDrafts] = useState>>({});
const [open, setOpen] = useState(defaultState?.open ?? false);
/** The menu row under the highlight, or null when it is hidden. */
const [lit, setLit] = useState(defaultState?.highlight ?? null);
const [glide, setGlide] = useState({ top: 0, height: 0 });
const [message, setMessage] = useState('');
const rows = useRef<(HTMLButtonElement | null)[]>([]);
const selectRef = useRef(null);
const buttonRef = useRef(null);
const valuesRef = useRef(values);
valuesRef.current = values;
const editedRef = useRef(edited);
editedRef.current = edited;
const id = useId();
const enabled = autoplay && playing && !defaultState;
const starting = useRef(start);
starting.current = start;
const aim = useRef(target);
aim.current = target;
const options = useRef(typeOptions);
options.current = typeOptions;
/** A change the reader made: it marks the card edited and is reported. */
const commit = (next: FineTuneValues, field?: NumberKey) => {
setValues(next);
if (field) setTouched((was) => ({ ...was, [field]: true }));
if (!edited) setMessage(`${title}: ${editedLabel.toLowerCase()}`);
setEdited(true);
onChange?.(next);
};
const setNumber = (key: NumberKey, value: number) => {
const field = FIELDS.find((f) => f.key === key)!;
const next = clamp(Math.round(value), field.min, field.max);
if (next === valuesRef.current[key]) return;
commit({ ...valuesRef.current, [key]: next }, key);
};
// The demo agent: one pass of edits, a pause, and back to the start, for as long as it plays.
useEffect(() => {
if (!enabled) return;
let stopped = false;
let frame = 0;
const timers: number[] = [];
const wait = (ms: number) =>
new Promise((resolve, reject) => {
timers.push(window.setTimeout(() => (stopped ? reject(STOP) : resolve()), ms));
});
const count = (key: NumberKey, to: number, duration: number) =>
new Promise((resolve, reject) => {
const from = valuesRef.current[key];
const began = performance.now();
setBusy(key);
setTouched((was) => ({ ...was, [key]: true }));
const tick = (now: number) => {
if (stopped) return reject(STOP);
const t = Math.min(1, (now - began) / duration);
setValues((was) => ({ ...was, [key]: Math.round(from + (to - from) * easeInOut(t)) }));
if (t < 1) frame = requestAnimationFrame(tick);
else {
setBusy(null);
resolve();
}
};
frame = requestAnimationFrame(tick);
});
const reset = () => {
setValues(starting.current);
setTouched({});
setDrafts({});
setOpen(false);
setLit(null);
setBusy(null);
if (editedRef.current) setRound((n) => n + 1);
setEdited(false);
};
const script = async () => {
const goal = aim.current;
const list = options.current;
for (;;) {
reset();
await wait(1200);
setValues((was) => ({ ...was, layout: goal.layout }));
await wait(700);
await count('width', goal.width, 700);
await wait(300);
await count('height', goal.height, 500);
await wait(300);
await count('radius', goal.radius, 600);
await wait(300);
await count('opacity', goal.opacity, 500);
await wait(500);
const pick = Math.max(0, list.indexOf(goal.type ?? ''));
setOpen(true);
await wait(400);
for (let row = 0; row <= pick; row++) {
setLit(row);
await wait(row === pick ? 450 : 380);
}
setValues((was) => ({ ...was, type: list[pick] ?? null }));
setOpen(false);
setLit(null);
await wait(400);
setEdited(true);
await wait(3000);
}
};
script().catch((error) => {
if (error !== STOP) throw error;
});
return () => {
stopped = true;
cancelAnimationFrame(frame);
timers.forEach(window.clearTimeout);
setBusy(null);
setOpen(false);
setLit(null);
};
}, [enabled]);
// The highlight follows its row: offsets are read from the layout.
useLayoutEffect(() => {
if (lit === null) return;
const row = rows.current[lit];
if (row) setGlide({ top: row.offsetTop, height: row.offsetHeight });
}, [lit, open]);
// An open menu closes on a press outside it.
useEffect(() => {
if (!open) return;
const close = (event: PointerEvent) => {
if (!selectRef.current?.contains(event.target as Node)) setOpen(false);
};
document.addEventListener('pointerdown', close);
return () => document.removeEventListener('pointerdown', close);
}, [open]);
const openMenu = (focusRow: boolean) => {
const chosen = values.type ? typeOptions.indexOf(values.type) : -1;
setOpen(true);
setLit(chosen >= 0 ? chosen : focusRow ? 0 : null);
if (focusRow) requestAnimationFrame(() => rows.current[Math.max(0, chosen)]?.focus());
};
const closeMenu = (refocus: boolean) => {
setOpen(false);
setLit(null);
if (refocus) buttonRef.current?.focus();
};
const choose = (index: number) => {
const type = typeOptions[index];
closeMenu(true);
if (type !== values.type) commit({ ...values, type });
};
const onButtonKey = (event: ReactKeyboardEvent) => {
if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
event.preventDefault();
openMenu(true);
} else if (event.key === 'Escape' && open) {
event.preventDefault();
closeMenu(false);
}
};
const onMenuKey = (event: ReactKeyboardEvent) => {
const last = typeOptions.length - 1;
const now = lit ?? 0;
const go = (row: number) => {
event.preventDefault();
setLit(row);
rows.current[row]?.focus();
};
if (event.key === 'ArrowDown') go(now >= last ? 0 : now + 1);
else if (event.key === 'ArrowUp') go(now <= 0 ? last : now - 1);
else if (event.key === 'Home') go(0);
else if (event.key === 'End') go(last);
else if (event.key === 'Enter' || event.key === ' ') {
event.preventDefault();
choose(now);
} else if (event.key === 'Escape' || event.key === 'Tab') {
if (event.key === 'Escape') event.preventDefault();
closeMenu(event.key === 'Escape');
}
};
const onLayoutKey = (event: ReactKeyboardEvent) => {
const index = LAYOUTS.findIndex((l) => l.value === values.layout);
const step =
event.key === 'ArrowRight' || event.key === 'ArrowDown'
? 1
: event.key === 'ArrowLeft' || event.key === 'ArrowUp'
? -1
: 0;
if (!step) return;
event.preventDefault();
const next = (index + step + LAYOUTS.length) % LAYOUTS.length;
commit({ ...values, layout: LAYOUTS[next].value });
(
event.currentTarget.querySelectorAll('button')[next] as HTMLButtonElement | undefined
)?.focus();
};
return (