Tempo Harness

Appearance

UI / Tailwind (project conventions) ​

Mobile/PWA is a first-class priority — design mobile-first with comfortable touch targets.

Behaviour patterns (the observability contract, error/empty-state recipes, the anti-patterns catalogue) live in docs/agents/ui-patterns.md; the visual direction (palette, type, layout) in docs/design.md. Read those when building or fixing a feature's UI.

ALL UI work — components, templates, pages, new or edited — follows docs/design.md § Fundamentals and § The intentional design protocol. In brief: state the surface's job in one sentence; rank content by importance and assign visual weight to match (rank-then-weight — contrast/weight/colour, never size alone); the gap is the grouping signal (outer gap > inner gap); containment ladder whitespace → tint → shadow → border; labels are a last resort; every edit is ONE promote/demote/align intent executed through the weight-carrying properties. Variants are named hypotheses, never layout shuffles; after a variant is marked "close", one intent per round on the frozen base.

Visual states are authored as Storybook stories — the prop-driven look of a component (each structural state + content stress on its dynamic props), beside the component as Foo.stories.ts. The authoring conventions (the three-way Vitest / Pest-browser / Storybook boundary, the content-provenance taxonomy, the two-axis state matrix) live in docs/agents/storybook.md. storify-on-touch: when you change a component's appearance, add or update its story in the same change — a restyle without a story update is drift the VRT net can't catch.

Wireframe first — converge in an Artifact before touching Vue ​

For a new UI surface or a layout rework (not a copy tweak, restyle, or bugfix), the design conversation happens in a throwaway HTML wireframe published as a claude.ai Artifact — and code starts only once the maintainer approves a direction there. Failing in a wireframe costs minutes; failing in a built page costs a PR round-trip. (Established in the Today-page alerts rework, #840.)

The wireframe contract:

  • Real content, not lorem — populate with the feature's actual data shapes so layout problems surface.

  • Mobile-width frames first, plus a desktop treatment note; show the key states (busy, quiet/empty, error) — the busy state is usually the one that breaks a design.

  • Multiple directions when the problem is open (2–3 options with trade-offs and a recommended default); iterate the same artifact URL as feedback lands, one labelled version per round.

  • A feature-preservation map when consolidating or moving UI — every existing affordance gets a named new home, so nothing is silently dropped.

  • Throwaway by design — the wireframe lives in the session scratchpad, never committed; the approved direction is captured by the PR/issue body, and the built UI is then proven by stories + VRT as usual.

  • Utility-first: compose from utility classes on the markup. Don't reach for @apply to recreate component classes. Extract a Vue partial when the same markup appears a 2nd time, or when a class list grows past a glance (~8–10 utilities) — name it for what it is (TaskCard.vue, not Box.vue). Duplication in markup is fine until it repeats.

  • Reuse the shadcn-vue kit first. components/ui/* already ships Button, Dialog, Input, Select, Sheet, Alert, Skeleton, Sonner, … — check there before hand-rolling one, and keep utility overrides on a kit component minimal (a class or two, not a reskin).

  • Destructive actions confirm through the shared ConfirmDialog (built on the shadcn Dialog kit) — never native window.confirm. Drive it off a ref, run the action in the confirm handler:

    vue
    <ConfirmDialog
    v-model:open="confirmingDelete"
    title="Delete this person?"
    description="This can't be undone."
    @confirm="destroy"
/>

  • Stay on the scale tokens. p-4/text-sm/rounded-lg, never arbitrary p-[17px]/text-[13px]; colours, shadows and radii come from the design.md § Foundations token tiers (bg-card, shadow-card, rounded-card), never bg-[#…] or shadow-[…]. npm run lint:design enforces this in CI — an off-scale colour/shadow/radius/spacing/font-size arbitrary fails the build (sanctioned exceptions: active:scale-[0.96], text-[10px] micro-labels, any var()/calc() token reference; a genuine one-off carries a design-lint-allow line comment). Layout arbitraries (w-[…], ring-[3px], transition-[…]) are out of scope. Classes are sorted by prettier-plugin-tailwindcss — don't hand-order.

  • Mobile-first responsive. Base utilities target the phone; layer up at sm:/md:/lg: — never style desktop then undo it downward. Keep primary actions (Done / Punt / send) at ~44px touch targets. Use semantic elements (<button>, <nav>, <label>), visible focus states, and labels tied to inputs.

  • Form inputs render ≥16px on mobile (text-base with sm:/md:text-sm to shrink on desktop) — a smaller font on an <input>/<textarea> triggers iOS Safari's auto-zoom-on-focus, which yanks the layout. Never suppress it with maximum-scale=1 (breaks pinch-zoom, fails WCAG resize). The shadcn Input kit already does this — keep the pattern when composing forms. This is a functional iOS quirk for inputs only — not a floor on UI text, which floors at ~12px (10px for sanctioned micro-labels); see design.md § Type scale.

  • Gate: bun run format, bun run lint:check, bun run types:check.

  • Generate Wayfinder before running the FE gate locally — resources/js/{actions,routes,wayfinder} are gitignored/generated, so lint:check/types:check throw misleading import/order + TS2307 Cannot find module '@/routes/…' errors until you run php artisan wayfinder:generate --with-form (CI does this first). The errors are missing generated files, not your change.

Component emits & props ​

  • Declare every custom event in defineEmits. A listener the parent binds (@linked) that the child hasn't declared falls through as a native DOM attribute. On a component with a fragment or text root — more than one root node, or a bare text root — Vue has no single element to attach it to and warns at runtime: "Extraneous non-emits event listeners (…) were passed to component but could not be automatically inherited because component renders fragment or text root nodes." The fix is to declare the event, not to silence the warning.

    vue
    <!-- PersonaLinkButton.vue renders TWO roots — a <button> and <PersonaLinkModal> — -->
<!-- so it's a fragment root and MUST declare what it emits, or @linked/@unlinked warn. -->
<script setup lang="ts">
const emit = defineEmits<{
    linked: [link: PersonLink];
    unlinked: [];
}>();
</script>

  • A single-root component auto-inherits undeclared attrs/listeners onto its root — fine until you don't want that forwarding, in which case set inheritAttrs: false and bind explicitly. A fragment root has no such fallback, so its events must be declared.

  • Type props with defineProps<{…}>() (no runtime props: {} object); keep shared prop shapes in @/types/*, not inline anonymous types.

  • A local ref seeded from a prop snapshots once — const x = ref(props.x) won't update when fresh props arrive (an Inertia redirect after a server-side mutation, e.g. a chat-driven assign). Either derive it with computed (no copy), or pair the ref with watch(() => props.x, v => (x.value = v)) to re-sync. A chip that kept its pre-mutation value is this bug (PersonaLinkButton.vue).

  • Bind the kit Switch (and other reka-ui kit toggles) with v-model, never v-model:checked. reka-ui's SwitchRoot exposes modelValue / update:modelValue — there is no checked prop or update:checked event. v-model:checked (or :checked + @update:checked) is a silently dead binding: the toggle renders its default state regardless of the data and never writes back, with no warning. This bug recurred across #274, #354, #426 — bind v-model, and assert the rendered data-state (checked/unchecked) in a browser test against a non-default initial value. See docs/learnings/2026-06-12-reka-switch-v-model-checked-dead.md.

Motion & interaction polish ​

Tempo is low-motion by design (design.md MOTION dial 2). Motion is for feedback, never ambience — added movement is a regression, not polish (see the anti-patterns catalogue). So:

  • The one sanctioned micro-interaction is a press: active:scale-[0.96] on primary buttons for tactile feedback (never below 0.95). That's the ceiling — no stagger-in, blur-in, or slide-in entrance animations, no page-load animation on first render.
  • Respect prefers-reduced-motion. A global @media (prefers-reduced-motion: reduce) guard in app.css neutralises transitions + animations (including the press) for users who ask the OS for less motion — calm by default, calmer on request. Never author motion that ignores it.
  • Transition specific properties, never transition: all — transition-colors, transition-[box-shadow], etc. all animates layout/paint props you didn't mean to and is the usual cause of janky hover.
  • Interruptible by default: CSS transitions for interactive state (the user can reverse them mid-flight); reserve @keyframes for a one-shot staged sequence. Don't reach for will-change unless you've measured a need.