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 guide its layout
Use shared tokens for color, type, spacing, size, corners, and motion. Prefer built-in scales over arbitrary values
Keep a clear hierarchy and only the actions people need. Skip decorative panels and unnecessary controls
Define shared text styles by role. Don't override size, weight, tracking, or line height locally
For a new design system, use few sizes and weights with clear size differences. Keep headings strong and body text quiet
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
Use the same treatment for matching surfaces, including glass. Avoid double borders; use smaller inner corner radii to keep gaps even
Apply themes to sheets, menus, native controls, and browser UI. No initial flash or transitions when switching
Prefer interactive demos. Reuse real product components and framing in demos, previews, and shared images
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

Define gutters, headers, scrolling, and footers in shared layouts. 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
Give sections generous spacing and keep related elements close. Remove spacing left by deleted content
Match control heights and baselines. Tabs and paired action buttons share equal widths; standalone controls fit content, sidebar controls fill their column
Align headings, text, and actions across columns. Keep alignment with wrapped text, empty screens, and dense content
Keep button labels on one line with room around text and icons. Correct alignment by eye
Fit dialogs to their content. Keep them within the viewport and scroll any 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 edge to edge, including padding. Give small icons comfortable hit areas

Controls

Prefer native controls. Preserve editing, selection, gestures, and keyboard shortcuts when customizing them
Provide buttons and keyboard controls for drag and swipe actions
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. On submit, focus the first invalid field. Don't block typing during validation
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

Show loading states where the content belongs. Use skeletons in place of missing content; don't add extra loaders or temporary layouts
Skip loaders for quick responses. Never delay a result to show one
Keep content during refresh and drafts after errors. Preserve focus, selection, and scroll unless the action changes them
Clear account data when switching accounts
Center screen-level empty states in the available space
Disable pending actions, not unrelated controls. Prevent duplicate submissions
Show a check or “Copied” for one second after copying. Keep feedback on the control; use toasts when a result needs 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; never delay input
Move the keyboard, sheet, and attached actions together, including during a drag. Keep nested scrolling, paging, and dismissal from interfering
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, concise and specific. Use familiar words and direct verbs
Lead with the point. Stop when it's made. Keep paragraphs short, with one idea each
Write for the reader. Focus on what they can do or gain
Trust the reader. Remove repeated labels, values, obvious instructions, and technical details they don't need
Skip forced cleverness, flattery, and stock phrases. Use comparisons only when they help explain the point
Use formatting to help scanning. Sentence-case headings, ampersands in titles, minimal bold, no decorative emoji or em dashes
Balance headings and short descriptions without adding filler or leaving lone words
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
Define shared values and rules once. Use shared helpers to format numbers, dates, units, and addresses
When renaming, update related labels, identifiers, routes, files, config, and docs automatically. Preserve unrelated and third-party names
Use what the framework, SDKs, and libraries already provide 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 cover purpose, stack, structure, setup, and usage. Use clear headings and short sections; link to details
Design docs link to real components and finished screens
Keep lasting rules and context in AGENTS files; leave out work logs. Update the relevant doc when behavior changes; don't repeat facts across files

Workflow

Fix repeated behavior problems in shared components. Record lasting 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

Checks