@deslop/coding-standards 0.1.1082 → 0.1.1085

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deslop/coding-standards",
-  "version": "0.1.1082",
+  "version": "0.1.1085",
   "repository": {
     "type": "git",
     "url": "https://github.com/MP281X/deslop",

package/skills/design/SKILL.md

@@ -1,158 +1,81 @@
 ---
 name: design
-description: 'UI and UX rules for product screens, creative pages and visual explanations. Use when building, prototyping or reviewing a component, page, diagram, review page or other rendered agent output.'
+description: 'Use before building, mocking or judging a screen, component or web page, before rendering an explanatory page, and before taking a screenshot or recording, composing or editing a video that shows a change.'
 ---
 
 # Design
 
-Follow the engineering skill and the repository's `CODING_STANDARDS.md` when present; where it sets a style, such as square borders, it wins over this skill.
+Follow engineering and the repository's `CODING_STANDARDS.md`.
 
-**The bar.** Build what people recommend for its polish and simplicity: Linear, T3 Code, Apple's own apps and apple.com. A person who is not technical uses it without help. The repository's existing screens are the floor, not the target: raise them through a pattern change that updates every screen, never through one screen that diverges.
+**The bar.** Calm, fast screens in the class of Linear, T3 Code and Apple's own apps: the content and the next action read at a glance, every input answers at once, and a person who is not technical finishes the task without help or explanation. Existing screens are the floor; raise them with a pattern change to every screen, never one screen that diverges.
 
-**Two modes.** Product mode works inside an app and follows every rule below. Creative mode covers websites, launch pages and motion pieces with no product to match; it adds [Creative mode](#creative-mode) and keeps every other rule.
-
-## Before the first draft
-
-1. **Task and feeling.** Name the person, their task, their context and the feeling the product gives, such as calm, fast or trustworthy. Name three qualities the person notices, each with what "excellent" looks like.
-2. **Baseline.** Name the category and platform, and the reference screen for each screen you build: in product mode the canonical screen per engineering's Patterns, otherwise one of Apple's apps on iOS or a reference the user named. Capture the reference in the states you need. Start from the system or established component defaults.
-3. **Range.** When the reference screen and the Taste section of `CODING_STANDARDS.md` do not settle the structure, compare 2–3 structurally different solutions on the same data. Include a simpler solution that removes unnecessary controls. Develop only the chosen direction.
-4. **States.** List every screen, its reachable states (empty, loading, partial, error, success, long content) and the events between them, before any code. Group states by concern instead of multiplying every combination.
-5. **Settled choices.** Carry forward what the user approved and what he removed. Never re-add a removed element, rename a visible term or change an approved detail without a request.
+**Less is more.** Empty space is a material: it groups, ranks and lets the content breathe. Start from the content and the next action, and add a control, label, section, color or decoration only for the request, the reference or a rule here; never fill a gap because it is empty. A crowded screen is fixed by removing: fewer elements, borders, colors, sizes and words, each one larger and clearer.
 
 ## Decide
 
-**Standard first.** Each screen and interaction follows the convention people know from the reference. Copy its structure, controls, gestures and states. Depart from it only for a deliberate improvement that a capture beside the reference proves. In product mode, make such an improvement only when the request covers it, as a pattern change to every screen per engineering's Patterns.
-
-**Fewest parts.** Start from the content and the next action. Add a control, label, section, color or decoration only when the request, the reference screen or a rule below needs it. When the user calls a screen bloated or wrong, remove parts before you add any.
+- **Standard first.** Each screen copies the convention people know from its reference: in product mode the canonical screen per engineering's Patterns, otherwise Apple's apps or a reference the user named. Depart only for an improvement a capture beside the reference proves.
+- **One meaning.** Each element adds information, a distinct action or a relationship. One action has one control in one place. No heading, summary, badge or text restates what the screen already shows. Keyboard shortcuts and screen-reader labels are not repetition.
+- **Zero clicks.** What the task needs is visible: the important value, warning and next action never sit behind a menu, tab, hover or expand. Each frequent action is one click; a choice the app can make is not asked.
+- **Current work first.** The first viewport shows real content and the next action; completed work recedes without hiding.
+- **Range.** When the reference and the Taste rows leave the structure open, compare 2–3 structurally different solutions on the same data, including one with fewer controls; build only the chosen one. A website or a new kind of piece starts from three concepts that differ in structure or metaphor, not palette.
+- **States.** List each screen's reachable states (empty, loading, partial, error, success, long content) before code. Never re-add an element the user removed or rename a visible term without a request.
 
-**One meaning.** Each visible element adds information, enables a distinct action or shows a relationship. Each action has one control in one place, apart from the gestures and menus the reference repeats. Delete repeated headings, summaries, counts, badges, wrappers and text that restates the visible state. Keyboard shortcuts and screen-reader labels are not repetition.
+## Hierarchy
 
-**Current work first.** The first viewport shows real content and the next action, not an introduction. Open the current step, diminish completed work without hiding it, and show prerequisites and time expectations where they help.
+Blur a capture: the primary content and next action still stand out.
 
-**Hierarchy.** Blur a capture: the primary content and the next action still stand out.
-
-- Unequal priorities get unequal weight. Mute labels, metadata and chrome before you enlarge content; metadata never looks like user content.
-- Each decision area has one strongest action. Gaps inside a group are smaller than gaps between groups.
-- The accent marks actions and selection, status colors mark states, and chart colors mark series.
-- Put detail on demand, but never hide a consequential warning or an essential action.
-
-| Content                       | Treatment                                                                    |
-| ----------------------------- | ---------------------------------------------------------------------------- |
-| Comparable records or options | Aligned rows and columns with consistent order, units and metadata placement |
-| Familiar action               | A conventional icon with an accessible name                                  |
-| Ambiguous action              | A clear text label, never a guessed icon                                     |
-| Explanation                   | The real state or example first; text only for missing context or impact     |
+- Unequal priorities get unequal weight; mute labels, metadata and chrome before you enlarge content.
+- One strongest action per decision area; gaps inside a group are smaller than between groups.
+- The accent marks actions and selection, status colors mark states, chart colors mark series.
+- Comparable records sit in aligned rows and columns. A familiar action is a conventional icon with an accessible name; an ambiguous one a text label.
 
 ## Build
 
-**Components.** Reuse the existing renderer, states and interactions for the same role, and read its source. Add a missing primitive through the repository's registry command and keep its defaults. Fix a wrong shared pattern at its owner.
-
-**Native platforms.** On iOS, build from the system primitives in the current release's style, such as SwiftUI views through `@expo/ui`. They cover navigation, toolbars, search, lists, menus, swipe actions, sheets and SF Symbols. Glass belongs to controls and navigation, never to content. The repository's mobile theme sets colors and type; never draw a custom version of a system control.
-
-**Surfaces.** Use the existing theme, tokens and semantic colors; add no hardcoded color or size. Group by proximity before borders or elevation, and nest no cards. Give each shared edge one border owner, and use translucent border tokens that pick up their background. Build elevation from stacked shadows at 5% black, each with offset equal to blur: 1, 2, 4 and 8 pixels for small elevation. Nested corners are concentric: the inner radius is the outer radius minus the padding between them.
-
-**Color.** Keep neutrals at one temperature, and derive subtle fills from the main neutral at 10% opacity. Match peer colors by perceived lightness in OKLCH, not HSL; darker shades of a hue gain chroma. Text meets WCAG AA: 4.5:1, or 3:1 for large text. Ease an overlay gradient with 15 smoothstep stops instead of a two-stop fade, and interpolate gradients `in oklch`.
-
-**Typography.** Use semantic text styles: on iOS the system styles with a 17 point body, on the web the existing scale.
-
-- Use at most five sizes on a screen. Start leading at 1.5 for body, 1.3 for subheadings and 1.1 for headings.
-- Track uppercase labels +0.08em, body 0 and display −0.022em. In dark mode, lower a variable weight by 20. Prose lines hold 45 to 75 characters.
-- Use tabular figures for changing or compared numbers, and right-align numeric columns. Use real quotes, apostrophes, dashes and `…`.
-- Truncate names in the middle when the end tells them apart, such as a file extension.
-
-**Alignment.** Use as few edges and axes as the layout allows. Related headings, search, rows and dividers share one grid and inset, and headers share columns with row contents. Align icons of different shapes by their centers and labels by one edge. Equivalent controls share size, icon style, stroke, radius, fill and hit target. Balance by eye where shapes differ, and encode the offset in the owning component: a button with a trailing arrow starts at 12 pixels left and 9 right. Trace a defect to its cause:
-
-| Defect                             | Cause                                  | Repair                                                                             |
-| ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------- |
-| Squashed icon or avatar            | A fixed-size flex child shrinks        | `shrink-0` keeps its canonical box                                                 |
-| Trailing action disappears         | The content track refuses to shrink    | `min-w-0` on the content and `shrink-0` on the control, or a shrinkable grid track |
-| Accessory drifts in a tall row     | It follows wrapped text                | Center the accessory in the row, independent of the text                           |
-| Counts shift during updates        | Proportional digits or mixed formats   | `tabular-nums` with consistent locale and units                                    |
-| Accents or tall scripts clip       | Tight line height or text-box clipping | Fix the owning type scale or overflow; never shrink the font to fit                |
-| Missing metadata leaves separators | Empty optional slots still render      | Omit orphaned separators and lines                                                 |
-
-**Interaction contracts.**
-
-- Hit targets are at least 24 pixels, and 44 on touch. Mobile inputs use 16 pixels or more, the right input type, paste and autofill.
-- Keep focus visible, restore it after a dialog, and close a dialog with Escape. Keep standard keyboard behavior.
-- The URL holds navigation state, and Back restores the scroll position and the draft.
-- Place an error beside its field and move focus to the first one. Undo or confirm a destructive action.
-- When the app already knows an action is not allowed, disable it and show the reason beside it.
-- Selecting "All" clears the filter; never store or show "All" as one more filter value.
-
-**States and speed.** A loading state has the layout of the loaded content, and a loader waits before it appears. Use stale-while-revalidate for cached data. Apply writes optimistically and roll back on failure without losing the person's place. Start unavoidable work early, and add no artificial wait. Errors and rare states get the same care as the main path.
-
-**Copy.** Name actions after the person's task, with one vocabulary and sentence case. An empty state offers the next action. An error names what failed and the recovery that exists, beside its control.
-
-**Motion.** Motion explains a state change or a spatial relationship: plan its trigger, source and destination with the interaction. It never delays input or decorates.
-
-- Frequent actions and typing get no animation. Keep tweens under 300 ms, ease-out for entrances and ease-in-out for morphs. Interface springs start at a 0.4 second duration with 0.15 bounce.
-- An entrance starts near its resting size, from 0.9 scale or more. A surface anchored to a trigger enters and exits from it.
-- Replace content with a crossfade, never exit then entry. Stagger repeated items slightly.
-- A drag follows the finger, keeps velocity on release and resists at its bounds instead of stopping hard. Let people interrupt any motion.
-- Reduced motion keeps the feedback without movement. Inspect slowed intermediate frames, not only the final one.
-
-**Access and phones.** The whole task works on a phone, with keyboard, touch and zoom. Text reflows at 200% and with Dynamic Type instead of clipping. Bottom controls clear the keyboard and safe areas. Never remove an accessible affordance for minimalism.
-
-## Prototype and tune
-
-**Mocks.** Start the mock from the real screen: copy its rendered markup, theme tokens and fonts from the running app or its source, then change only what the decision needs. Keep its components, copy, spacing, realistic data and main states. For a native app, imitate the platform's system look; the mock settles structure, flow and the rough look. Add interaction only when manipulating the subject exposes a consequential difference; never add tabs or a state dashboard merely to navigate the explanation.
-
-**Real host.** The real host is the browser preview for the web and the simulator for a native app; settle the final native appearance there, and revise the affected design instead of defending the earlier mock.
-
-**Tune.** Settle values yourself. For values you cannot settle by reasoning, such as spacing, timing, springs or blur, capture candidates side by side, including both extremes, and judge them against the reference. Write the chosen values into the source and recapture.
+- **Theme.** Before web UI work, read the repository's shadcn theme, the CSS file its `components.json` names under `tailwind.css`. The look lives only there: a change to color, radius, type, spacing or shadow goes into the theme's tokens for every screen and keeps them consistent, never into a page or a primitive.
+- **Web components.** shadcn's primitives, used as shipped. The registry changes often, so list it before you choose: `vpx shadcn@latest list @shadcn -t registry:ui`, then `vpx shadcn@latest docs <name>` for the chosen one. When shadcn has the component, use it with its own variants, props and sizes; add a missing one with `shadcn add` and its defaults. Never a wrapper, a new variant, a restyle or a hand-built replacement; `className` only places a primitive in the layout. Needing heavy customization means the wrong primitive or pattern.
+- **iOS.** The same shadcn look, carried by native iOS elements: the mobile theme's tokens for color, radius and type on SwiftUI primitives through `@expo/ui` (navigation, toolbars, search, lists, menus, swipe actions, sheets, SF Symbols) with their system sizes and behavior. Glass for controls and navigation, never content. Never draw a custom system control.
+- **Surfaces and color** come from the theme's tokens and semantic colors only: no raw colors, shadows or radii. Group by proximity before borders; no nested cards; one border owner per edge.
+- **Flat.** Never a gradient, glow or blurred shadow, anywhere: screens, pages, videos and images use flat theme colors and even 1 px borders, never a colored stripe on one side.
 
-## Critique before showing
+  ```tsx
+  <div className="bg-card border" />                          // good
+  <div className="bg-linear-to-b from-muted to-background" /> // bad: no-gradient
+  ```
 
-Capture the result at the reference's size, theme, data and state, and put it beside the reference. Review it in four separate passes, measure each defect and record the repair:
+- **Type.** The theme's semantic styles, at most five sizes per screen, prose 45–75 characters, tabular figures for changing numbers, middle truncation when the end distinguishes names.
+- **Alignment.** Few edges; headers share columns with rows; equivalent controls share size, icon style and hit target. Squashed icon: `shrink-0`. Vanishing trailing action: `min-w-0` on content. Empty optional slots render no orphan separators.
+- **Interaction.** Inputs with the right type and autofill; visible focus restored after a dialog; Escape closes it; the URL holds navigation state and Back restores scroll and draft; errors beside their field; destructive actions undo or confirm; a known-forbidden action is disabled with its reason beside it; "All" clears a filter.
+- **Speed** at the level of [T3 Code](https://github.com/pingdotgg/t3code), the reference to read for it: every input answers in the next frame from local state, and the network catches up behind it. Loading keeps the loaded layout and appears after a delay; cached data shows stale while revalidating; reversible writes apply optimistically and roll back without losing the place.
+- **Copy.** Actions named after the task, sentence case, one vocabulary; an empty state offers the next action; an error names what failed and the recovery.
+- **Motion** explains a state change or spatial relationship and never delays input. No animation on frequent actions or typing. Tweens under 300 ms, ease-out entrances, ease-in-out morphs, springs 0.4 s with 0.15 bounce, entrances from 0.9 scale or more, anchored surfaces enter from their trigger, content swaps crossfade, drags keep velocity and resist at bounds, every motion interruptible, reduced motion keeps feedback without movement.
+- **Phones.** The whole task works on a phone with touch, keyboard and zoom; text reflows at 200% and Dynamic Type; bottom controls clear the keyboard and safe areas.
 
-1. **Structure.** Does the screen open on current work? Is anything redundant, hidden or missing for the task? In product mode, compare the entry route, sections, controls, visible terms, copy and states with the canonical screen; each difference without a request is a defect.
-2. **Behavior.** Do states, focus, errors, gestures and motion behave like the reference? Replay transitions and loop joins.
-3. **Visual.** Check hierarchy, alignment, spacing, type, color, icon consistency and the generic tells below.
-4. **Context.** Does it carry the named feeling and the three qualities? Where does a person hesitate?
+## Mocks
 
-Repair in this order: grouping, hierarchy, alignment, copy, then states. Recapture after each batch, and stress long names, Unicode, 0, 1 and many records, the narrow phone and dark mode. Misalignment and inconsistent controls stay defects when types and tests pass. Show the result with captures per delivery's captures.
+The user chooses by seeing and trying, never by reading a description.
 
-| Generic tell                                    | Check                                                 |
-| ----------------------------------------------- | ----------------------------------------------------- |
-| Every section is a bordered card with an icon   | Each container groups something; remove the others    |
-| Everything has equal prominence                 | The blurred capture still shows the primary content   |
-| Each tile gets its own accent color             | Every hue names a state, series or action             |
-| An emphasized headline word or decorative label | Removing the treatment loses no meaning, so remove it |
-| Generic copy such as "seamless" or "Learn more" | Each label names its capability or the outcome        |
-| Content that waits for an entrance animation    | The first frame is readable and actionable            |
+- **Real base.** Start from the real screen: copy its rendered markup, theme tokens and fonts from the running app or its source, change only what the decision needs, keep realistic data and the main states. A native mock imitates the system look; the simulator settles the final appearance.
+- **The ask, visible.** Each change the user requested is visible against the current screen: before beside after, the changed region marked.
+- **Variants.** An open direction gets three variants, two when a third would only pad. Each tests one named hypothesis about structure or interaction (where the action lives, what the list groups by, inline edit or a sheet), never palette or spacing; all share the same data, states and copy; the interactions the decision turns on work.
+- **Comparison.** One page shows every variant as a choice: its name, its hypothesis in one line, what it costs. Mark a recommendation without hiding the others; the user picks or combines. At 390 px, show paired full-width crops of the deciding region first, then each full screen; never shrunken screens side by side.
 
-## Creative mode
+## Critique
 
-Ground the page in its subject: name the audience and the page's one job, and take the visual language from the subject's world. Open with the most characteristic thing in its best form, such as a live demo, an image or a headline, and give the product one memorable signature. Interaction, navigation and reading stay conventional; novelty lives in composition, imagery and one choreographed moment. Concept before code: compare three compositions that differ in structure, not palette, and build the winner whole. Avoid defaults that read as generated: a cream canvas with a serif and a clay accent, identical rounded cards with soft shadows, all-caps eyebrows, and the hero, feature table, logo row and email form skeleton.
+Capture the result at the reference's size, theme, data and state, beside the reference. First measure in the page: list elements wider than the viewport or their container, text clipped by its box and fonts that did not load, and fix each. Then check in order:
 
-## Visual explanations
+1. **Structure.** Opens on current work; nothing repeated, hidden or missing; route, sections, controls, terms and copy match the canonical screen unless the request changed them.
+2. **Behavior.** States, focus, errors, gestures and motion match the reference; replay transitions.
+3. **Visual.** Hierarchy, alignment, spacing, type, color, icons, and these tells: any gradient or glow, a colored stripe on one side of a card, quote or code block, every section a bordered card with an icon, equal prominence everywhere, a color per tile, decorative emphasized words, generic copy such as "seamless", content waiting on an entrance animation, and generated defaults: cream canvas with serif and clay accent, identical rounded cards, all-caps eyebrows, the hero, feature grid, logo row and email form skeleton.
 
-These rules cover diagrams, review pages and agent answers. Transmit a specific message with the fewest words and least effort. Write that message privately before choosing the form. Markdown lists, tables and embedded captures are visual representations. Use them directly when they carry the message; do not rebuild them in HTML. HTML complements Markdown only when a necessary spatial relationship, motion or direct manipulation exceeds Markdown's capabilities. Name that added capability privately before rendering; decoration is not one. Use a sentence when it is clearer. Never turn a source list, process recap or checklist into a dashboard.
+Repair grouping, then hierarchy, alignment, copy and states; recapture with long names, Unicode, 0, 1 and many records, the narrow phone and dark mode.
 
-| The reader asks                      | Exhibit                                                        |
-| ------------------------------------ | -------------------------------------------------------------- |
-| What does it look like now?          | Real capture, or a named system view with changed parts marked |
-| What changed on screen?              | Before and after pair with the same data, the old state left   |
-| Which transitions are allowed?       | State machine with forbidden edges marked                      |
-| What happens in order, and who acts? | Sequence in swimlanes, one lane per actor                      |
-| Where did the time go?               | Timeline with bars on one time axis                            |
-| How much faster, bigger or cheaper?  | Bars on a shared axis, values printed on the bars              |
-| Where exactly is the defect?         | Annotated capture with numbered markers and short notes        |
-| Which requirement has which proof?   | Coverage grid of requirements against proof, colored by state  |
-| How do the parts relate?             | Named actors and explicit relationships; no unlabeled blocks   |
-| Which option is better?              | Options side by side at the same size and with the same data   |
-| What will a video show?              | Storyboard of chapter frames, the outcome frame marked         |
+**Captures** show the result: screenshots for layout, a video for behavior. The real application only, with realistic data in the user's theme, cropped to the subject and readable on a phone; record at phone width when desktop text is too small. Inspect each file before you show it; a capture is stale once a component it shows changes.
 
-When none fits, choose the form that matches the data's shape; draw a list as a list.
+**Video.** A proof video is a short motion piece the user wants to watch, composed per delivery's Captures; a raw recording only for one action under ten seconds.
 
-- **One message.** The first visible state must state the actual change, comparison or consequence. Put the relevant names, direction, units and state on the subject. Use a sentence only when the graphic otherwise requires guessing. A decorative title or recap is not a substitute for that meaning.
-- **One dominant element.** Size, weight and position show importance; mute context. Use the available width without stretching an empty stage. Add each shape, label and surface only for a relationship or action it communicates. Isometric depth belongs to a meaningful layer or ownership boundary, not arbitrary slabs.
-- **Honest scale.** Bars start at zero on one linear scale; draw a range as a range.
-- **Labels.** Put names, values and units on the data, with one scale per comparison. Labels and captions stay under twelve words, and a visual holds no paragraphs.
-- **Real content.** Use actual names, operations and relationships. Keep a proposal distinct from an applied change, and a simulated explanation distinct from application evidence. A physical model is useful only when its operation explains the concept without another metaphor to decode.
-- **Interaction.** Keep the message understandable without a click. Add a control only to explore a real alternative or change an assumption. A predetermined change uses an automatic sequence, not a required click. On a phone, keep essential comparisons visible; do not hide the answer in tabs or menus.
-- **Motion.** Animate the subject from its real source to its destination. Keep identity, scale, alignment and unchanged context stable. Use transform and opacity, not per-frame layout. Make transitions 180–350 ms and uninterrupted, with no decorative pulses; pause only to let the reader see a state. Replay a demonstration only when one pass is easy to miss, and make its reset distinct from an undo. Do not use an invisible one-shot movement as the only explanation.
-- **Host.** Match the enclosing UI's typography, density, controls, surfaces and semantic tokens, not only its colors. Keep the outer background transparent and remove unnecessary card wrappers. Prefer native CSS for simple automatic diagrams; use relative geometry instead of JavaScript sizing when it gives the same result.
-- **Proof.** Inspect the artifact in its actual host, including an intermediate frame and the final state. A valid file, a correct model or a headless screenshot alone does not prove readable, smooth, correctly triggered motion. Compare before and after at the same scale and actual playback speed. Fix a repeated failure in its representation or source, not with more prompt prohibitions.
-- **Check.** Use the host's theme variables, check light, dark and a 390-point width, and fix clipping, overlap and contrast before you show it. At that width the page stays under about 400 points tall.
+- **Storyboard** before recording: per chapter the claim, the focal element, the input and the payoff. Two to four chapters, 15–35 s in total, one dataset and one recurring object across chapters.
+- **Open** on the real subject in the first frame, its value visible within 3 s: no title card, introduction or idle time. **End** on the verified outcome, framed by the reveal and held at least 2 s.
+- **Camera** with a purpose per move: the wide shot sets context, a push lands before each input, the view stays still while the change happens, the reveal holds. Real speed for the meaningful action; label accelerated footage.
+- **Consistency.** Every video keeps one look: a dark backdrop from the app's theme with the app's primary as the only accent, the app's font, one caption style, one input marker, one chapter transition, one easing family and visible chapter progress. Energy rises only around the one reveal.
+- **Captions.** One per chapter, a benefit in at most six words, for meaning the footage lacks.
+- **Check** frames scaled to 390 px wide: app text and captions read without zoom. Replay the file and check an intermediate frame.