SYSTEM.md

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; respect platform conventions
  • Use shared tokens for color, type, spacing, size, corners, and motion. Prefer built-in scales
  • Define text styles by role, with clear hierarchy and no local overrides. New systems use few sizes and weights
  • Use existing or native components, then VS™ Modules. Contribute reusable improvements back to the library
  • Keep existing or native icons; otherwise use VS™ Icons. Use one shared component with consistent strokes, corners, and text color; never mix sets or draw replacements
  • Size icons beside text from the font. Prefer 1cap and baseline alignment on web; correct optical differences centrally
  • Match surface treatments, including glass. Avoid double borders; use smaller inner radii for even gaps
  • Theme sheets, menus, native controls, and browser UI. No initial flash or transitions when switching themes
  • Prefer interactive demos using real product components. Reuse their framing in previews and shared images
  • Compress media without visible loss, serve appropriate sizes, and load visible assets first. Archive originals outside the repo
  • Prefer video to GIFs. Keep loops pausable and use stills for reduced motion

Layout

  • Build around the primary task. Keep headings and illustrations proportionate; remove decorative panels and unnecessary controls
  • Define gutters, headers, scrolling, and footers in shared layouts. Reserve space for fixed controls and safe areas
  • Keep text columns readable; give tables, charts, and demos enough width
  • Keep related visuals, copy, and actions close; separate distinct groups. Don't stretch sparse content or retain gaps from removed elements
  • Align headings, text, and actions within groups and across columns, even with wrapped or missing content. Separate action alignment belongs in shared toolbars or footers
  • Center screen-level empty states, including their action, in the available space
  • Reflow small screens without shrinking type or clipping controls. Wrap choices or use dropdowns; reserve sideways scrolling for media

Controls

  • Preserve native editing, selection, gestures, shortcuts, autofill, OTP suggestions, and zoom
  • Provide button and keyboard alternatives to dragging and swiping
  • Use tabs for a few choices, dropdowns for longer lists. Omit single-option selectors and unnecessary steps
  • Match heights and baselines. Equal widths for tabs and paired actions; standalone controls fit content, sidebar controls fill their column
  • Keep button labels on one line with room for text and icons. Check alignment by eye
  • Make interactive rows clickable edge to edge, including padding. Label icon controls and give small targets comfortable hit areas
  • Fit menus and dialogs to content within the viewport, above surrounding UI. Scroll overflow
  • Menu triggers toggle and stay active while open. Support keyboard navigation, Escape, and outside dismissal
  • Style focus to match the UI and keep it visible. Restore focus to the trigger when dialogs close
  • Use consistent input labels, useful placeholders, appropriate keyboards, and native clear, paste, or copy actions. Autofocus clear input flows, not mobile browsing
  • Show errors beside fields; focus the first invalid field on submit. Never block typing during validation
  • Keep input decorations inside the field with matching padding; clicking them focuses the input
  • Make hover and press subtle but visible; don't rely on color alone. Only interactive elements look clickable or use pointer cursors
  • Match selection, carets, and placeholders to the UI. Keep content and inputs selectable, control labels unselectable

States

  • Preserve size, position, spacing, and type across states. Reserve media space; use skeletons where content will appear, without 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
  • Disable pending actions and prevent duplicate submissions; keep unrelated controls usable. Check whether writes succeeded before retrying
  • Keep feedback on the control; use toasts for separate messages. After copying, show a check or “Copied” for one second
  • Update affected views without refresh. Optional data must not block the page; discard stale requests
  • Label estimates and unknown values; don't substitute zero

Motion & navigation

  • Use shared motion and native transitions. Keep animations quick and interruptible; respect reduced motion and never delay input
  • Prefer transform for movement and scaling; animate layout properties only when layout must change
  • Fade whole elements with opacity; use color alpha for individual fills, borders, or text. Alpha changes can repaint
  • Move keyboards, sheets, and attached actions together during drags. Keep nested scrolling, paging, and dismissal from interfering
  • Prefer native scroll-edge effects. Fade content, not fixed controls or borders; avoid hard cutoffs or painted bands
  • Animate changed labels and values through shared text transitions. Use tabular numbers; don't replay unchanged content
  • Use real links and short URLs with shareable filters, tabs, and page numbers
  • Preserve Back and Forward, saved preferences, and destinations through sign-in

Copy

  • Lead with what the reader can do or gain. Use plain English, familiar words, and direct verbs
  • Keep paragraphs short, with one idea each. Stop when the point is made
  • Fix confusing layouts before adding explanations. Cut filler taglines, repeated labels or values, and unnecessary technical details; keep guidance needed to act or avoid mistakes
  • Skip forced cleverness, flattery, and stock phrases. Use comparisons only to clarify
  • Format for scanning: sentence-case headings, ampersands in titles, minimal bold, no decorative emoji or em dashes
  • Avoid lone words in headings and short descriptions
  • Summaries and PRs: short bullets, no trailing periods

Code & docs

  • Group files by feature. Share logic, assets, and formatting helpers across apps; keep platform code local
  • Reuse components for matching appearance and behavior. Fix recurring problems there; keep one-off fixes local
  • Renames update related labels, identifiers, routes, files, config, and docs. Preserve unrelated and third-party names
  • Prefer existing project code, then platform features, then installed dependencies, then new code. Add dependencies only when they meaningfully reduce complexity
  • Solve the whole task with the least code that's easy to read. Avoid speculative abstractions, wrappers, options, and configuration
  • Simplification must preserve validation, error handling, security, and accessibility
  • Comment on non-obvious decisions and known limits, including when to revisit them
  • Generate metadata and share cards from page content. Keep canonical URLs and sitemaps aligned 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. Keep project commands short and consistent across repos; link to details
  • Design docs link to real components and finished screens
  • Keep lasting rules and context in AGENTS files, without work logs. Update relevant docs when behavior changes; don't duplicate facts

Workflow

  • Improve usability and make code easy for developers and agents to change. Preserve unrelated behavior
  • Read the affected code and trace its callers before editing. Include every change needed to complete the task; leave unrelated improvements alone
  • Compare regressions with the last working version before adding workarounds
  • Report what changed, what remains unverified, and any material limitations
  • 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