Personal defaults for working with agents.

Design

Follow the existing design system. Without one, start with monochrome, clear contrast, and a subtle accent
Keep names, appearance, and behavior consistent across screens and platforms; respect native conventions. Let each page's purpose shape its layout
Use shared tokens for color, type, spacing, size, corners, and motion. Prefer built-in scales over arbitrary values
Keep UI minimal: clear hierarchy, essential actions, no decorative panels or unnecessary controls
Define shared text styles by role. No local size, weight, tracking, or line-height overrides
For a new design system, use few sizes and weights, clear size jumps, strong headings, and quiet body text
Use VS™ Modules when existing project or native components don't cover the need. Add reusable components and improvements back to the library
Keep existing or native icon sets. Otherwise use VS™ Icons through a shared component. Match stroke, corners, optical size, and text color; don't mix sets or draw replacements
Matching surfaces share one treatment, including glass. No double borders. Inner corners use smaller radii so the gap stays even
Apply themes to sheets, menus, native controls, and browser UI. No initial flash or transitions when switching
Prefer interactive product demos. Demos, previews, and shared images reuse real product components and framing
Compress media and serve appropriate sizes without noticeable quality loss. Archive originals outside the repo; keep only assets the project uses
Load visible media first; defer the rest. Prefer video to GIFs, with pause controls and a still image for reduced motion

Layout

Shared layouts own gutters, headers, scrolling, and footers. Leave room for fixed controls and safe areas
Keep text columns readable; give tables, charts, and demos the width they need
No layout shifts. Reserve media and loading space; preserve size, position, spacing, and type across states
Favor generous section spacing; keep related elements close. Remove leftover spacing when content is removed
Match control heights and baselines. Tabs and paired action buttons share equal widths; standalone controls fit content, sidebar controls fill their column
Align corresponding headings, text, and actions across columns, even when copy wraps differently
Keep layouts aligned with empty screens, long text, and lots of content
Keep button labels on one line with room around text and icons. Correct alignment by eye
Dialogs fit their content, with a viewport limit and scrolling for overflow
Reflow on small screens; don't shrink type or clip controls. Wrap choices or use dropdowns; sideways scrolling is for media
Make interactive rows clickable through their padding. Small icons still need comfortable hit areas

Controls

Prefer native controls. Preserve editing, selection, gestures, and keyboard shortcuts when customizing them
Drag and swipe actions also work with buttons and the keyboard
Reuse shared components for appearance and behavior: loading, clearing, copying, disabled states
Use tabs for a few choices, dropdowns for longer lists. Skip single-option selectors and unnecessary steps
Keep menus on-screen and above surrounding content. Scroll long lists within a maximum height
Menu triggers toggle and stay active while open. Support keyboard navigation, Escape, and outside dismissal
Replace default browser focus rings with subtle styles that match the UI. Keep input and keyboard focus clear
Don't hide focused controls behind overlays. Return focus to the opening control when dialogs close
Inputs use consistent labels and spacing, useful placeholders, appropriate keyboards, and built-in clear, paste, or copy actions
Show errors beside fields; focus the first invalid field on submit. Validate without blocking typing
Place decorative input icons, prefixes, and suffixes inside the field with matching padding; clicking them focuses the input
Autofocus clear input flows, not mobile browsing. Keep paste, autofill, OTP suggestions, and zoom working
Make hover and press visible but subtle. Label icon controls; don't rely on color alone or make noninteractive elements look clickable
Style text selection, carets, and placeholders to match the UI. Use pointer cursors only for clickable elements
Keep control labels unselectable; content and inputs stay selectable

States

Load inside the existing surface. Skeletons replace missing content inside its real frame; don't stack loaders or temporary layouts
Skip loaders for quick responses; don't delay results just to show a loader
Keep content during refresh and drafts after errors; clear account data when switching accounts. Preserve focus, selection, and scroll unless the action changes them
Center screen-level empty states in the available space
Disable pending actions, not unrelated controls. Prevent duplicate submissions
Copy shows a check or “Copied” for one second. Keep feedback on its control; use toasts for results needing a separate message
Update affected views without a refresh. Optional data must not block the page; discard stale requests
Label estimates and unknown values; don't substitute zero
Check whether a write succeeded before retrying

Motion & navigation

Use shared motion and native transitions. Keep animations quick and interruptible; they must not delay input
Keyboard, sheet, and attached actions move together, including during a drag. Nested scrolling, paging, and dismissal must not fight each other
Prefer native scroll-edge effects. Fade content, not fixed controls or borders; avoid hard cutoffs and painted bands
Animate changing labels and values through shared text transitions, including button text. Use tabular numbers; don't replay unchanged content; respect reduced motion
Use real links so opening in another tab works. Keep URLs short; include shareable filters, tabs, and page numbers
Preserve Back and Forward, saved preferences, and destinations through sign-in

Copy

Plain English, ultra-concise. No slogans, jargon, filler, invented feature names, or em dashes
Lead with what people gain. Back claims with real numbers, examples, or customers
Remove repeated labels, values, obvious instructions, and technical details users don't need
Balance headings and short descriptions to avoid awkward breaks and lone words on the last line. Don't add filler to make lines match
Summaries and PRs: short bullets, no trailing periods

Code & docs

Keep feature files together. Share common logic and assets across apps; keep platform code local
Keep shared values and rules in one place. Format numbers, dates, units, and addresses through shared helpers
Renames automatically update related labels, identifiers, routes, files, config, and docs; preserve unrelated and third-party names
Use existing framework, SDK, and library features before adding dependencies or custom code
Keep project commands short and consistent across repos; list them in the README
Generate titles, descriptions, and OG text and images from each page's content. Keep canonical URLs and sitemaps in sync with public, indexable routes
Remove replaced code, unused assets and wrappers, and stale docs in the same change
READMEs: purpose, stack, structure, setup, usage. Plain English, clear headings, short sections; link to details
Design docs link to real components and finished screens
AGENTS files hold lasting rules and context, not work logs. Update the owning doc when behavior changes; don't repeat facts across files

Workflow

Turn repeated corrections into shared fixes: behavior in components, design decisions in rules. Keep one-off fixes local
Compare regressions with the last working version before adding workarounds
Don't build, test, launch, benchmark, automate browsers or simulators, or start servers unless I ask
Commit, push, merge, deploy, or release only when asked. “Commit and push” means all changes unless I say otherwise

Odyssey