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 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