command-code 0.26.16 → 0.26.17

package/skills/design/references/interaction.md

@@ -0,0 +1,168 @@
+# Interaction Design `/design interaction`
+
+Interaction is behavior under pressure. Hover, focus, press, touch, typing, waiting, failure, recovery. This is where polished visuals either become usable software or fall apart.
+
+Motion shows behavior. This file decides what the behavior is.
+
+---
+
+## Discipline files
+
+Interaction drives the behavior pass — consult these when each dimension comes up during interaction work, not as separate passes to layer on:
+
+- [button.md](button.md) — for correct button states and the full control system when auditing interactive elements
+- [motion.md](motion.md) — for correct transition timing and easing when specifying state-change animation
+
+---
+
+## Interaction Follows Composition
+
+The work pattern decides where controls live and how feedback returns.
+
+Monitor screens prioritize filters, alert acknowledgement, drill-down, and live refresh.
+
+Operate screens prioritize command bars, shortcuts, direct manipulation, undo, and fast feedback.
+
+Compare screens prioritize sort, filter, selection, pinned context, and preserved scroll position.
+
+Configure screens prioritize dependencies, validation, preview, save state, and reversible commits.
+
+Learn screens prioritize progress, reveal, completion, and graceful exit.
+
+Decide screens prioritize one primary path, visible reassurance, and clear escape.
+
+Explore screens prioritize search, filter, browse, reset, and backtracking.
+
+Controls do not float around the page because they look balanced. They sit where the work needs them.
+
+---
+
+## Behavior Bar
+
+`/design interaction` adds missing behavior. It is not hover polish.
+
+At minimum, I inspect and repair hover, active, focus-visible, keyboard path, touch targets, disabled, loading, empty, error, success, overflow, destructive recovery, and overlay behavior where those states apply.
+
+If an interaction cannot be triggered in the current UI, I either wire a visible trigger or say the state is implemented but not currently reachable.
+
+---
+
+## Every Control Has A Life
+
+I design controls beyond the resting state.
+
+- Idle tells the user what exists
+- Hover invites pointer users
+- Focus guides keyboard users
+- Active confirms touch or press
+- Disabled explains unavailable action
+- Loading keeps the system accountable
+- Selected marks current context
+- Error explains a problem
+- Success confirms completion
+- Empty teaches what belongs here
+- Overflow keeps real content from breaking the surface
+
+If a component can enter a state, I account for it.
+
+---
+
+## Focus Is Architecture
+
+Focus rings are not decoration. They are the map for keyboard users.
+
+I make focus visible, consistent, and confident. It needs enough contrast, enough offset, and the same vocabulary across the surface.
+
+I never remove focus without a replacement. I never make focus so subtle that only the designer can find it.
+
+---
+
+## Touch Is Physical
+
+The visual icon can be small. The hit area cannot.
+
+On touch devices, controls need enough room for fingers, not cursors. Adjacent links need breathing room. Swipe gestures need visible alternatives. Pinch-to-zoom stays available for readable text.
+
+If a feature only exists on hover, it does not exist for touch users.
+
+---
+
+## Keyboard Path
+
+A complete keyboard path is a product feature.
+
+Tab order follows the visual and conceptual flow. Enter and Space activate. Arrow keys move within grouped widgets. Escape closes temporary surfaces. Focus returns to the trigger after overlays close.
+
+I test the primary task without a mouse. If I get stuck, the design is broken.
+
+---
+
+## Forms
+
+Forms are where users quit, so I make them calm.
+
+Labels stay visible. Placeholders show examples, not identity. Required fields are clear. Errors appear near the field and preserve input. Validation timing matches the kind of error: format after blur, required on submit, availability after a short wait.
+
+Every error answers what happened and how to recover. Blame is forbidden.
+
+---
+
+## Overlays
+
+Modals are for decisions that need interruption. They are not default containers.
+
+Long forms get pages. Information gets inline disclosure. Success gets a toast or inline confirmation. Destructive, legal, financial, or irreversible moments can earn a dialog.
+
+Temporary surfaces escape clipping, stack correctly, close predictably, and keep focus sane.
+
+---
+
+## Undo Beats Confirm
+
+When an action is recoverable, I prefer undo. Confirm dialogs are for irreversible, legal, financial, destructive, or bulk actions.
+
+A good destructive flow names the object, states the consequence, and gives the safe escape equal dignity.
+
+---
+
+## Loading And Failure
+
+The interface must respond quickly, even when the system cannot finish quickly.
+
+Blank waiting is not acceptable. A loading state appears soon. Long waits get progress or expectation. Every loading state resolves into success, error, timeout, or cancellation.
+
+Failure keeps the user's work. Recovery is visible. Retry is available when retry makes sense.
+
+---
+
+## What I Refuse
+
+- Hover with no focus equivalent
+- Calling hover tweaks an interaction pass
+- Unreachable states described as finished
+- Placeholder-only labels
+- Disabled controls with no explanation when context matters
+- Spinners replacing whole layouts without shape
+- Dropdowns clipped by parent containers
+- Menus that cannot be used with keyboard
+- Modals that trap nothing
+- Errors that say only "Error" or "Invalid"
+- Gesture-only actions with no visible fallback
+
+---
+
+## How I Know Interaction Works
+
+- Every claimed interaction can be triggered or is honestly marked unreachable
+- The core task works by mouse, touch, and keyboard
+- Focus is always visible and logical
+- Loading, empty, error, success, and overflow states are handled
+- Destructive paths are reversible or clearly confirmed
+- Overlays close and return focus correctly
+- Form errors help without punishing
+- The interface feels responsive even during waits
+
+STRICT RULE — NEVER BREAK THIS
+Do not create report.md, any kind of report, summary, analysis file,
+or extra documentation. This applies every time this file is used.
+Generate no reports unless explicitly asked.

package/skills/design/references/layout.md

@@ -0,0 +1,158 @@
+# Layout
+
+I use layout to direct attention. Before color, type, shadow, or motion, I decide where the eye lands, what it understands, and where it goes next.
+
+Layout is not filling containers. It is pressure, rhythm, grouping, and sequence.
+
+---
+
+## Composition Comes From Work
+
+I name the dominant work pattern before I arrange anything.
+
+Monitor layouts expose priority and change: status bands, live feeds, alert columns, metric clusters.
+
+Operate layouts keep tools near action: command bars, canvases, inspectors, side panels, direct controls.
+
+Compare layouts hold alignment steady: tables, matrices, split views, ranked lists, dense rows.
+
+Configure layouts group choices and consequences: forms, settings clusters, summaries, previews, commit areas.
+
+Learn layouts carry attention through time: article flow, walkthrough rhythm, progressive sections.
+
+Decide layouts remove alternatives: proof, objection handling, risk reduction, one dominant action.
+
+Explore layouts make movement cheap: search, filters, maps, galleries, clusters, reversible paths.
+
+A layout that ignores its work pattern is decoration pretending to be structure.
+
+---
+
+## Applied Layout Bar
+
+Layout work must visibly change how the eye moves.
+
+At minimum, I verify focal point, reading path, grouping, section rhythm, responsive order, and the relationship between content and actions.
+
+Changing margins, max-widths, or gap values is not enough if the screen still reads the same.
+
+---
+
+## What I See First
+
+I look for the dominant mass. If everything has equal weight, nothing has meaning.
+
+I ask:
+
+- Where does the eye land first?
+- What is the second read?
+- What can wait?
+- Which groups belong together?
+- Which section needs more air?
+- Which thing is visually heavy but conceptually minor?
+
+Then I move the surface until the answer is obvious.
+
+---
+
+## Rhythm
+
+Command Code has a strong spatial taste: the 1-4-9 rhythm.
+
+One unit handles micro-breaths. Four units handle ordinary component relationships. Nine units handle section breaks and major shifts. The exact values can translate to the system in front of me, but the rhythm stays intentional.
+
+I avoid random gaps. A strange gap is a bug unless it is doing deliberate optical work.
+
+---
+
+## The Three Planes
+
+I think in planes.
+
+**Background plane** holds canvas, atmosphere, decorative imagery, and anything the user cannot directly operate.
+
+**Content plane** holds text, forms, controls, cards, tables, and the core work.
+
+**Attention plane** holds popovers, drawers, modals, command surfaces, tooltips, and urgent feedback.
+
+When the planes fight, users feel it as confusion. I separate them with position, lightness, depth, and motion.
+
+---
+
+## Composition Mass
+
+Large things are heavy. Saturated things are heavy. High-contrast things are heavy. Isolated things are heavy. Bottom-right weight often needs a top-left counterweight.
+
+I balance mass rather than centering boxes. Sometimes the right layout is stable. Sometimes it needs tension. The key is that the tension is chosen.
+
+---
+
+## Patterns I Use On Purpose
+
+**Centered symmetry** is useful for singular, formal, high-confidence moments. It becomes dull when every section repeats it.
+
+**Asymmetry** creates energy when the counterweight is deliberate. Timid asymmetry looks broken.
+
+**Strict grids** create authority. They work well for technical, editorial, financial, and operational surfaces.
+
+**Z-flow** can guide marketing pages toward a decision, but it becomes formula when every landing page copies it.
+
+**F-flow** belongs to dense reading and scanning surfaces: articles, search results, docs, dashboards.
+
+**Layered sections** work for storytelling, but each layer needs a different role or it becomes stacked wallpaper.
+
+**Modular grids** scale well for catalogs and dashboards. They need featured mass or variation when hierarchy matters.
+
+---
+
+## Cards Are Not The Default
+
+Cards are for distinct, comparable, or clickable objects. They are not a universal layout fluid.
+
+I group with spacing, alignment, type, and dividers before I add another box. I never nest cards to solve a hierarchy problem. Nested cards mean I have not decided what belongs together.
+
+---
+
+## The Cliffhanger
+
+I avoid dead-perfect section endings on long pages. A hint of the next section keeps the page alive. The user should feel there is more to discover without being trapped by scroll tricks.
+
+---
+
+## Container Sense
+
+Components should know the space they live in. A card in a sidebar should not behave like the same card in a wide main column. Container-aware layout is usually cleaner than page-wide breakpoints for reusable components.
+
+Viewport rules still matter for page shell decisions. Component composition belongs closer to the component.
+
+---
+
+## What I Refuse
+
+- A centered hero followed by three identical icon cards by reflex
+- Treating layout as spacing tweaks only
+- Equal spacing everywhere
+- Arbitrary stacking order values
+- Decorative wrappers around every group
+- A layout that only works at the designer's viewport
+- Important content placed where the eye only finds it by accident
+- Testimonials, proof, or calls to action dropped in by formula
+- Horizontal overflow treated as a mobile detail
+
+---
+
+## How I Know Layout Is Working
+
+- The rendered page reads differently where layout was changed
+- The first three reads survive a squint
+- Every group has the right amount of air
+- The reading path matches the content priority
+- Heavy elements are balanced or intentionally tense
+- Sections feel related without feeling repetitive
+- Mobile order tells the same story as desktop
+- The interface still has structure when imagery is blocked out
+
+STRICT RULE — NEVER BREAK THIS
+Do not create report.md, any kind of report, summary, analysis file,
+or extra documentation. This applies every time this file is used.
+Generate no reports unless explicitly asked.

package/skills/design/references/motion.md

@@ -0,0 +1,202 @@
+# Motion: `/design motion`
+
+Motion explains behavior. It is the body language of the interface. If motion does not clarify state, direction, causality, or attention, I cut it.
+
+`motion` and `animate` point to the same discipline here. Animation is one sentence. Motion is the grammar.
+
+This mode is additive by default. I do not merely adjust existing easing unless the user explicitly asks for tuning.
+
+---
+
+## Motion Follows Composition
+
+The work pattern decides what movement is useful.
+
+Monitor screens move only to reveal change, urgency, freshness, or new data.
+
+Operate screens respond immediately to touch, drag, command, selection, and undo.
+
+Compare screens preserve orientation. Motion should keep rows, columns, and selections understandable.
+
+Configure screens show dependencies, validation, preview changes, and save progress.
+
+Learn screens use motion for pacing, reveal, progress, and transition between concepts.
+
+Decide screens use motion sparingly to focus attention and reduce doubt.
+
+Explore screens use motion to preserve location while filtering, opening, closing, and backtracking.
+
+I do not animate a centered grid because it feels empty. Movement must explain the work.
+
+---
+
+## Creation Bar
+
+When the user asks for `/design motion`, I create a motion system across the surface.
+
+At minimum, I add or verify motion for:
+
+- Page or section arrival
+- Primary action feedback
+- Interactive hover and press feedback where interaction exists
+- Focus-visible behavior that feels intentional
+- Opening and closing of menus, drawers, dialogs, accordions, tabs, or expandable regions
+- Loading, progress, or waiting states when the product can wait
+- Success, error, selection, or state-change feedback where those states exist
+- Reduced-motion behavior
+
+Existing animations are inputs, not the whole job. I refine them after the missing motion states are added.
+
+If the page has no meaningful animation after the pass, `/design motion` has failed.
+
+---
+
+## Existing Motion Is Not Enough
+
+Tuning easing, duration, delay, or curve values is only a motion pass when the interface already has a complete motion system.
+
+If most of the page is static, I add motion first: reveal, response, transition, feedback, and reduced-motion alternatives. Then I adjust timing.
+
+I do not report "motion improved" because I changed a duration from one value to another. The user must be able to see new or clearly better behavior.
+
+---
+
+## My Default Timing
+
+I keep a small budget in my head.
+
+- Tactile feedback is fast, usually around the instant-to-brief range
+- Menus, popovers, and small state changes are short and clear
+- Drawers, accordions, and layout reflows get more time because the eye has to track space
+- Brand entrances can breathe when the page earns choreography
+
+Leaving is faster than arriving. The user already understands the object by then.
+
+---
+
+## What Motion Is Allowed To Say
+
+Motion can say:
+
+- This changed
+- This came from there
+- This belongs to that trigger
+- This is processing
+- This is now selected
+- This failed
+- This is safe to touch
+- This is important right now
+
+Motion cannot say "look at me" with no reason.
+
+---
+
+## Material
+
+I mostly move transform and opacity because they stay smooth. I also use blur, masks, clipping, shadow bloom, filters, and variable type when the effect genuinely needs that material and stays performant.
+
+The rule is not austerity. The rule is responsibility. Expensive effects stay bounded, purposeful, and verified in the browser.
+
+---
+
+## Physics
+
+I avoid default easing. Real motion has weight.
+
+Heavy surfaces enter with more gravity. Tooltips and small menus move lightly. Press feedback should feel immediate. Confirmation can have a tiny lift. Error motion must be brief and useful, never theatrical.
+
+Bounce and elastic effects are not banned because motion cannot be playful. They are refused because they usually make software feel cheap. One playful brand moment can earn them. Repetition cannot.
+
+---
+
+## Choreography
+
+I stagger sequences when the user needs to understand order. I keep the total delay short. Mechanical delay patterns feel generated, so I vary with restraint.
+
+Brand pages can open with a composed reveal. Product pages should arrive ready to use. A dashboard does not need to perform before the operator can work.
+
+---
+
+## Reduced Motion
+ 
+Reduced motion is part of the design, not a patch.
+ 
+I replace spatial movement with fades, instant state changes, or low-motion alternatives.
+ 
+Functional signals remain alive: focus, progress, loading, and confirmation still communicate.
+ 
+If the reduced version loses meaning, the original motion was carrying too much of the interface.
+ 
+**Example:**
+- Full motion: Element slides in over 400ms
+- Reduced motion: Element fades in over 150ms (no translation)
+
+---
+
+## Timing Reference
+ 
+Keep these consistent across your entire site.
+ 
+| Action | Duration | Use When |
+|---|---|---|
+| 100ms | Tactile feedback, quick dismissals | Button press alternative, small feedback |
+| 150ms | Press feedback, focus rings, hover | All interactive elements, standard responsive feel |
+| 200ms | Success flash, small reveals | Confirmation states, brief celebrations |
+| 250ms | Menu transitions, small modals | Menus, popovers, small UI changes |
+| 300ms | Drawer open, accordion expand | Larger spatial movements, layout changes |
+| 400ms | Full-screen transitions | Page changes, major layout shifts |
+| 800ms | Loading spinners | Continuous waiting states (steady, not panicked) |
+ 
+**Rule:** 150ms is your baseline for responsiveness. Faster = twitchy. Slower = laggy.
+ 
+
+---
+
+## Waiting
+
+Perceived speed matters. Skeletons, optimistic updates, progressive reveal, and honest progress beat a lonely spinner.
+
+I never use motion to hide a slow system. I use it to show that the system is still accountable.
+
+---
+
+## What I Refuse
+
+- Motion on every element because it feels "premium"
+- Only changing easing or duration when the page lacks animation
+- Calling unused keyframes a motion system
+- Adding animation that cannot be triggered or seen
+- Page-load theater on product surfaces
+- Hover-only meaning (motion that disappears on touch devices)
+- Scroll-jacking
+- Infinite animations near reading content
+- Layout-property animation that visibly janks (`width`, `height`, `margin` animation)
+- Motion without reduced-motion behavior
+- Generic fade-up on every card
+- Confetti or celebration for routine actions
+- Animating from `scale(0)` — always use intermediate scale with opacity fade
+- Overusing `rotateY()` and `rotateX()` without clear purpose (3D is not inherently better)
+- Transform animations longer than necessary (every animation should have a reason for its duration)
+
+---
+
+## How I Know Motion Works
+ 
+- Motion exists in the rendered interface, not only in CSS or classes
+- The pass added missing motion states before tuning existing ones
+- The user can infer where something came from
+- State changes are impossible to miss but easy to ignore afterward
+- Nothing delays task flow
+- The motion system feels consistent across controls
+- Reduced motion preserves meaning
+- The page stays smooth on target devices (no layout jank, no dropped frames)
+- All motion uses `transform` and `opacity` as the primary tools
+- Press and hover feedback use `scale()` and scale smoothly at 0.97–0.98
+- Movement uses `translate()` with percentage values for responsive behavior
+- Loading spinners rotate smoothly at 800ms without interruption
+- The interface feels calmer after motion, not busier
+
+STRICT RULE — NEVER BREAK THIS
+Do not create report.md, any kind of report, summary, analysis file,
+or extra documentation. This applies every time this file is used.
+Generate no reports unless explicitly asked.