{ "view": { "w": 1310, "h": 915 }, "stages": [ { "n": 1, "title": "Research", "checks": [ { "id": "RES-1", "title": "Define the user goal", "tool": "task analysis", "level": "v1", "done": "The screen's primary task is stated in one sentence, and the screen is organized around it.", "verify": "A new viewer can state the screen's purpose after five seconds.", "link": { "href": "/exercises/design-game", "label": "Play the design game" } }, { "id": "RES-2", "title": "Infer from the context of use", "tool": "defaults · history", "level": "v1", "done": "The screen derives defaults from context (time, location, device, prior actions) instead of asking.", "verify": "Each remaining question is one the screen cannot answer itself." }, { "id": "RES-3", "title": "Collect references", "tool": "Game UI Database · Mobbin", "level": "v1", "done": "A shipped interface for the same task was chosen as a reference, and its information structure was adopted.", "verify": "Side by side, the borrowed structure is visible.", "link": { "href": "/exercises/getting-specific-outcomes-by-remixing", "label": "Open the exercise" } }, { "id": "RES-4", "title": "Decompose a reference", "tool": "source · REA", "level": "v1", "done": "The reference's source was read, and every design choice it makes is recorded with its exact value.", "verify": "A rebuild made only from the record matches the original side by side.", "link": { "href": "https://github.com/morluto/rea", "label": "Get REA" } }, { "id": "RES-5", "title": "Inventory the content", "tool": "content inventory", "level": "v1", "done": "Every fact and action the screen could show was listed, and what did not belong was moved or removed.", "verify": "Every element on the screen appears in the inventory." }, { "id": "RES-6", "title": "Give each item one location", "tool": "information architecture", "level": "v1", "done": "Every fact and every action appears in exactly one place.", "verify": "No number or control can be found twice." } ] }, { "n": 2, "title": "Exploration", "checks": [ { "id": "EXP-1", "title": "Wireframe before styling", "tool": "wireframe", "level": "v1", "done": "The full task works in an unstyled version with real content.", "verify": "A user completes the primary task on the wireframe." }, { "id": "EXP-2", "title": "Generate concept art", "tool": "image generation", "level": "v1", "done": "Concept art of the finished screen, without added labels or slogans, was generated and a direction chosen before implementation.", "verify": "The implemented screen matches the chosen concept.", "link": { "href": "/exercises/beautiful-websites", "label": "Open the exercise" } }, { "id": "EXP-3", "title": "Compare variants", "tool": "design exploration", "level": "v1", "done": "Several distinct variants were compared side by side and one was chosen.", "verify": "The reasons for the choice can be stated.", "link": { "href": "/exercises/creativity-taste-authorship", "label": "Open the exercise" } } ] }, { "n": 3, "title": "Composition", "checks": [ { "id": "COMP-1", "title": "Set the hierarchy", "tool": "focal point · contrast", "level": "v1", "done": "The primary element has the highest contrast, and other elements decrease in emphasis by rank.", "verify": "In a one-second glance, viewers fixate on the intended element first." }, { "id": "COMP-2", "title": "Group by Gestalt principles", "tool": "proximity · common region", "level": "v1", "done": "Related elements are grouped by proximity and similarity rather than by borders and nested containers.", "verify": "Each remaining border separates something proximity cannot." }, { "id": "COMP-3", "title": "Test the layout at every size", "tool": "responsive layout", "level": "v1", "done": "No overlap, clipping, distortion, or misalignment at common sizes, with extreme content.", "verify": "Screenshots at phone, laptop, and wide sizes show no defects." } ] }, { "n": 4, "title": "Representation", "checks": [ { "id": "REP-1", "title": "Use conventional symbols", "tool": "iconography", "level": "v1", "done": "Standard actions and objects use conventional symbols or their own appearance instead of text labels.", "verify": "Every remaining label carries information the symbol cannot.", "link": { "href": "/exercises/design-game", "label": "Play the design game" } }, { "id": "REP-2", "title": "Encode quantities graphically", "tool": "pips · bars · common scales", "level": "v1", "done": "Small counts use pips or tallies, comparisons share a common scale, and repeated entities have one icon each.", "verify": "Key quantities can be read without reading numerals." }, { "id": "REP-3", "title": "Apply the five text tests", "tool": "Tufte · Norman · Krug · Nielsen", "level": "v1", "done": "Every string passed the five tests: not redundant (Tufte), not an instruction (Norman, Krug), not happy talk (Krug), relevant to the task now (Nielsen), and naming a value that can't identify itself (Refactoring UI).", "verify": "For each removed string, you can name the test it failed." } ] }, { "n": 5, "title": "Interaction", "checks": [ { "id": "INT-1", "title": "Make affordances visible", "tool": "signifiers · mapping", "level": "v1", "done": "Interactive elements are signified as interactive, placed on or beside what they affect, and each appears once.", "verify": "Every element that looks interactive is interactive." }, { "id": "INT-2", "title": "Add feedforward", "tool": "previews", "level": "v1", "done": "Before a commitment, the screen shows its outcome.", "verify": "No action produces an unexpected result." }, { "id": "INT-3", "title": "Apply progressive disclosure", "tool": "tooltips · inspectors", "level": "v1", "done": "Secondary detail opens from the object it describes, and nothing required for the primary task is hidden.", "verify": "The primary task can be completed without opening any tooltip." }, { "id": "INT-4", "title": "Give every action feedback", "tool": "visual · audio · motion", "level": "v1", "done": "Every action receives a response within about 100 ms, in at least two channels, scaled to its importance.", "verify": "Every input produces a perceptible response, exactly once." }, { "id": "INT-5", "title": "Design every state", "tool": "empty · loading · error", "level": "v1", "done": "Empty, loading, partial, and error states are designed, and errors state the means of recovery.", "verify": "Each state, forced with test data, appears intentional." } ] }, { "n": 6, "title": "Style", "checks": [ { "id": "STYLE-1", "title": "Define the art direction", "tool": "visual language", "level": "v1", "done": "Materials, rendering style, and tone are defined, and every component follows them.", "verify": "No component appears to come from a different visual language.", "link": { "href": "/exercises/beautiful-websites", "label": "Open the exercise" } }, { "id": "STYLE-2", "title": "Define typography and color", "tool": "type scale · semantic color", "level": "v1", "done": "Two type roles and a palette in which each hue has one meaning, backed by a second encoding.", "verify": "In grayscale, no information is lost." } ] }, { "n": 7, "title": "Critique", "checks": [ { "id": "CRIT-1", "title": "Run a squint test", "tool": "blur · grayscale", "level": "v1", "done": "The screen was viewed blurred and in grayscale, and the focal point was corrected where needed.", "verify": "The most visible element is the intended focal point." }, { "id": "CRIT-2", "title": "Run a slop audit", "tool": "deletion pass", "level": "v1", "done": "AI-default conventions were removed, and every remaining element was tested by deletion against the five text tests and the data-ink principle.", "verify": "No eyebrow, restated title, false sequence, status narration, usage hint, or meaningless border remains." }, { "id": "CRIT-3", "title": "Benchmark against the reference", "tool": "blind comparison", "level": "v1", "done": "The screen was compared unlabeled with its reference, and the largest deficiency was fixed.", "verify": "A new viewer does not judge it the weaker of the two." }, { "id": "CRIT-4", "title": "Run a usability test", "tool": "think-aloud protocol", "level": "v1", "done": "A new user attempted real tasks unassisted while observed.", "verify": "The three largest problems observed were fixed." }, { "id": "CRIT-5", "title": "Update the design system", "tool": "guidelines · AGENTS.md", "level": "v1", "done": "Successful fixes were applied across the app through shared styles and components, and their principles recorded where agents will read them.", "verify": "An agent applied one to a new screen without being told.", "link": { "href": "/library/skills", "label": "Read the guide" } } ] } ], "nodes": [ { "id": "screen", "label": "Screen", "tool": "", "logos": [], "glyph": "monitor", "x": 650, "y": 420, "w": 260, "h": 170, "kind": "part", "desc": "The surface on which a person reads information and acts on a system. Bret Victor's essay Magic Ink describes software design as graphic design (what the screen shows) combined with industrial design (how the system can be manipulated), and argues that most software is information software, used to learn, compare, and decide. The boxes around the screen are its properties, the research that precedes it, and the critique that follows it.", "views": {}, "checks": [], "prompts": [], "env": [ "same", "" ], "link": { "href": "../fractal-ai-accelerator/index.html", "zoom": "out" } }, { "id": "goal", "label": "User goal", "tool": "", "logos": [], "glyph": "target", "x": 125, "y": 230, "w": 218, "h": 44, "kind": "part", "desc": "The outcome a person wants from the screen: information to learn, a decision to make, or an action to take. Task analysis lists the steps and the information each step needs. Design proceeds from the goal to the interface, not from components to content; a screen serves one primary task, and secondary tasks support it or move elsewhere.", "views": {}, "checks": [ "RES-1" ], "prompts": [ "p-RES-1" ], "env": [ "same", "" ] }, { "id": "context", "label": "Context of use", "tool": "", "logos": [], "glyph": "clock", "x": 125, "y": 282, "w": 218, "h": 44, "kind": "part", "desc": "The users, tasks, equipment, and physical and social environment in which a product is used (ISO 9241-11). Context such as time, location, device, and prior actions lets software infer sensible defaults instead of asking. Victor calls interaction a cost: each question the screen asks requires the user to know what they want and how to express it.", "views": {}, "checks": [ "RES-2" ], "prompts": [ "p-RES-2" ], "env": [ "same", "" ] }, { "id": "refs", "label": "References", "tool": "", "logos": [], "glyph": "copy", "x": 125, "y": 334, "w": 218, "h": 44, "kind": "part", "desc": "Existing, shipped interfaces that solve the same task, collected in pattern libraries such as the Game UI Database and Mobbin. Following established patterns uses the user's prior learning (Nielsen's heuristic of consistency and standards: users spend most of their time in other products). Designers reuse proven information structures and make the visual style their own.", "views": {}, "checks": [ "RES-3" ], "prompts": [ "p-RES-3" ], "env": [ "same", "" ] }, { "id": "decompose", "label": "Decompose", "tool": "REA", "logos": [], "glyph": "code", "x": 125, "y": 386, "w": 218, "h": 44, "kind": "part", "desc": "Recovering a reference's exact design decisions from its source rather than its appearance. A website's HTML, styles, and scripts are readable in the browser, many products publish their code on GitHub, and REA (Reverse Engineer Anything) inspects apps whose source is not published. Each decision is recorded by category with its value (grid, type scale, palette, spacing, easing, states), and the record is tested by rebuilding the reference from it. Copying a master to learn the technique is an old practice: Benjamin Franklin rewrote Spectator essays from his notes and compared them with the originals. A remix keeps the technique and replaces the content and identity.", "views": {}, "checks": [ "RES-4" ], "prompts": [ "p-RES-4" ], "env": [ "same", "" ] }, { "id": "ia", "label": "Information architecture", "tool": "", "logos": [], "glyph": "folder", "x": 125, "y": 438, "w": 218, "h": 44, "kind": "part", "desc": "The structure of content: what exists, how it is grouped and labelled, and where each item lives. A content inventory lists every fact and action; each is then given one location. Duplicated information increases extraneous cognitive load (Sweller) without adding meaning, and raises the question of which copy is correct.", "views": {}, "checks": [ "RES-5", "RES-6" ], "prompts": [ "p-RES-5", "p-RES-6" ], "env": [ "same", "" ] }, { "id": "hierarchy", "label": "Hierarchy", "tool": "", "logos": [], "glyph": "layers", "x": 96, "y": 82, "w": 156, "h": 56, "kind": "part", "desc": "The order in which elements are perceived, established through contrast, size, position, and isolation. A screen has one focal point; other elements are ranked as primary, secondary, or tertiary. Information that is usually secondary is promoted only when its state changes, which is how status displays remain readable.", "views": {}, "checks": [ "COMP-1" ], "prompts": [ "p-COMP-1" ], "env": [ "same", "" ] }, { "id": "contrast", "label": "Contrast", "tool": "", "logos": [], "glyph": "contrast", "x": 258, "y": 82, "w": 156, "h": 56, "kind": "part", "desc": "Difference between elements along a visual variable: luminance, size, hue, saturation, weight, or motion. These are preattentive features, detected across the visual field in under about 250 milliseconds (Treisman), so the highest-contrast element is seen first. Legibility requires luminance contrast: WCAG sets 4.5:1 for body text, measured against the rendered background.", "views": {}, "checks": [ "COMP-1" ], "prompts": [ "p-COMP-1" ], "env": [ "same", "" ] }, { "id": "gestalt", "label": "Gestalt", "tool": "", "logos": [], "glyph": "gestalt", "x": 420, "y": 82, "w": 156, "h": 56, "kind": "part", "desc": "Principles from Gestalt psychology (Wertheimer, Koffka, Köhler) describing how perception groups elements: proximity, similarity, common region, continuity, closure, and figure–ground. Proximity and similarity group elements without borders or containers. Elements that look alike are read as the same kind of thing, so a heading must differ visibly from the items it introduces.", "views": {}, "checks": [ "COMP-2" ], "prompts": [ "p-COMP-2" ], "env": [ "same", "" ] }, { "id": "layout", "label": "Layout", "tool": "", "logos": [], "glyph": "align", "x": 582, "y": 82, "w": 156, "h": 56, "kind": "part", "desc": "The arrangement of elements in space: a grid, shared alignment axes, a consistent spacing scale, and whitespace. Responsive layout preserves the task across screen sizes rather than the geometry. A layout is tested with extreme content (the longest name, the largest number) and must show no overlap, clipping, or distortion.", "views": {}, "checks": [ "EXP-1", "COMP-3" ], "prompts": [ "p-EXP-1", "p-COMP-3" ], "env": [ "same", "" ] }, { "id": "iconography", "label": "Iconography", "tool": "", "logos": [], "glyph": "icons", "x": 767, "y": 82, "w": 160, "h": 56, "kind": "part", "desc": "The system of pictorial symbols in an interface. Conventional symbols (play, pause, close, copy) are recognized from prior learning; novel symbols must be learned and fail when they need a legend. An icon set shares a grid, stroke weight, and padding, and each icon has a distinct silhouette, which is the feature recognized first at small sizes.", "views": {}, "checks": [ "REP-1" ], "prompts": [ "p-REP-1" ], "env": [ "same", "" ] }, { "id": "dataviz", "label": "Data visualization", "tool": "", "logos": [], "glyph": "bars", "x": 955, "y": 82, "w": 196, "h": 56, "kind": "part", "desc": "The graphical encoding of quantities. Position on a common scale is decoded most accurately, then length, then angle and area (Cleveland and McGill). Small counts are read without counting, by subitizing, up to about four items, so pips and tallies read faster than numerals. Tufte's data-ink ratio favors removing ink that carries no data.", "views": {}, "checks": [ "REP-2" ], "prompts": [ "p-REP-2" ], "env": [ "same", "" ] }, { "id": "copy", "label": "Copy", "tool": "", "logos": [], "glyph": "pen", "x": 1155, "y": 82, "w": 184, "h": 56, "kind": "part", "desc": "All text in an interface. Five published tests decide whether a string stays. Redundancy: Tufte's principle \"erase redundant data-ink\" removes text that repeats what the screen already shows. Instruction: Norman holds that when simple things need labels or instructions, the design has failed, and Krug writes that instructions must die. Happy talk: Krug's term for text that says nothing specific. Relevance: Nielsen's heuristic 8, every extra unit of information competes with the relevant ones. Self-identification: Refactoring UI, labels are a last resort. Strings that pass are typically names, exact values, verbs on controls, warnings, and narrative.", "views": {}, "checks": [ "REP-3" ], "prompts": [ "p-REP-3" ], "env": [ "same", "" ] }, { "id": "typography", "label": "Typography", "tool": "", "logos": [], "glyph": "type", "x": 125, "y": 530, "w": 218, "h": 44, "kind": "part", "desc": "The selection and arrangement of type: typefaces, a type scale, weight, line length (about 45 to 75 characters for running text), and spacing. A common system pairs a display face for names and titles with a highly legible text face for rules and data. Tabular numerals keep changing values aligned.", "views": {}, "checks": [ "STYLE-2" ], "prompts": [ "p-STYLE-2" ], "env": [ "same", "" ] }, { "id": "color", "label": "Color", "tool": "", "logos": [], "glyph": "palette", "x": 125, "y": 592, "w": 218, "h": 44, "kind": "part", "desc": "A palette and the meanings assigned to it. Each hue encodes one meaning across the product (a state, a team, a resource). About 8% of men have a color vision deficiency (CVD), so color is paired with a second encoding such as shape, pattern, or position, and meaning should survive conversion to grayscale.", "views": {}, "checks": [ "STYLE-2" ], "prompts": [ "p-STYLE-2" ], "env": [ "same", "" ] }, { "id": "artdirection", "label": "Art direction", "tool": "", "logos": [], "glyph": "brush", "x": 125, "y": 654, "w": 218, "h": 44, "kind": "part", "desc": "The decisions that give a product one coherent visual language: materials, rendering style, period, and tone. Skeuomorphism renders interface elements after their physical counterparts, which signals what they are; flat design removes those cues. Interface components are derived from the chosen visual language, and containers remain consistent while their contents vary.", "views": {}, "checks": [ "EXP-2", "STYLE-1" ], "prompts": [ "p-EXP-2", "p-STYLE-1" ], "env": [ "same", "" ] }, { "id": "motion", "label": "Motion", "tool": "", "logos": [], "glyph": "motion", "x": 125, "y": 716, "w": 218, "h": 44, "kind": "part", "desc": "Animation that communicates change: an element's origin, destination, and cause. Interface transitions typically last about 100 to 300 milliseconds, with easing that resembles physical acceleration. Continuity of motion preserves object identity between views, and a single animated focal point avoids competing for attention.", "views": {}, "checks": [ "INT-4" ], "prompts": [ "p-INT-4" ], "env": [ "same", "" ] }, { "id": "affordance", "label": "Affordance", "tool": "", "logos": [], "glyph": "cursor", "x": 1190, "y": 280, "w": 214, "h": 52, "kind": "part", "desc": "The actions an object makes possible (Gibson; applied to design by Norman). Signifiers are the perceivable cues that indicate them, such as raised buttons and handles; mapping is the relationship between a control and its effect. Fitts's law: the time to reach a target depends on its distance and size, so frequent targets are large and near.", "views": {}, "checks": [ "RES-6", "INT-1" ], "prompts": [ "p-RES-6", "p-INT-1" ], "env": [ "same", "" ] }, { "id": "feedforward", "label": "Feedforward", "tool": "", "logos": [], "glyph": "coin", "x": 1190, "y": 350, "w": 214, "h": 52, "kind": "part", "desc": "Information presented before an action about its outcome, such as the remaining balance after a purchase or the item a choice replaces. It addresses Norman's gulf of execution, the gap between an intention and knowing which action achieves it. Effective previews show the consequences relevant to the current decision.", "views": {}, "checks": [ "INT-2" ], "prompts": [ "p-INT-2" ], "env": [ "same", "" ] }, { "id": "disclosure", "label": "Progressive disclosure", "tool": "", "logos": [], "glyph": "search", "x": 1190, "y": 420, "w": 214, "h": 52, "kind": "part", "desc": "Presenting essential information first and additional detail on request. Shneiderman's information-seeking mantra: overview first, zoom and filter, then details on demand. Detail moves into tooltips, inspectors, and contextual panels opened from the object they describe, and the primary task remains possible without opening any of them.", "views": {}, "checks": [ "INT-3" ], "prompts": [ "p-INT-3" ], "env": [ "same", "" ] }, { "id": "feedback", "label": "Feedback", "tool": "", "logos": [], "glyph": "bolt", "x": 1190, "y": 490, "w": 214, "h": 52, "kind": "part", "desc": "The system's response to an action, which addresses Norman's gulf of evaluation: whether the user can tell what happened. Responses within about 100 milliseconds feel instantaneous (Miller; Nielsen). Game design layers feedback across sight, sound, and motion, scaled to the event's importance, a practice called juice.", "views": {}, "checks": [ "INT-4" ], "prompts": [ "p-INT-4" ], "env": [ "same", "" ] }, { "id": "states", "label": "State", "tool": "", "logos": [], "glyph": "pulse", "x": 1190, "y": 560, "w": 214, "h": 52, "kind": "part", "desc": "The conditions a screen and its components can be in. Screens have ideal, empty, loading, partial, and error states; controls have default, hover, focus, pressed, disabled, and selected states. Nielsen's first heuristic, visibility of system status, requires each to be distinguishable. Error states identify the problem and the means of recovery.", "views": {}, "checks": [ "INT-5" ], "prompts": [ "p-INT-5" ], "env": [ "same", "" ] }, { "id": "squint", "label": "Squint test", "tool": "", "logos": [], "glyph": "eye", "x": 650, "y": 820, "w": 150, "h": 56, "kind": "part", "desc": "An evaluation of hierarchy: blurring the screen, squinting, or viewing it in grayscale removes detail and leaves luminance and mass. The element that remains most visible is the effective focal point. If information disappears in grayscale, it was encoded in hue alone.", "views": {}, "checks": [ "CRIT-1" ], "prompts": [ "p-CRIT-1" ], "env": [ "same", "" ] }, { "id": "slop", "label": "Slop audit", "tool": "", "logos": [], "glyph": "scissors", "x": 815, "y": 820, "w": 150, "h": 56, "kind": "part", "desc": "A review for the conventions AI-generated interfaces default to, each of which fails a published test. Eyebrow labels, subtitles that restate titles, duplicated counts, numbering of items that are not a sequence, and status narration are redundant data-ink (Tufte). Explanations of the screen and usage hints are instructions (Norman, Krug). Taglines and feature blurbs are happy talk (Krug). Nested borders and glow without meaning are non-data-ink. The audit ends with a deletion pass: remove each element, and restore only what passes the tests. Replacing words with unconventional symbols fails the instruction test.", "views": {}, "checks": [ "CRIT-2" ], "prompts": [ "p-CRIT-2" ], "env": [ "same", "" ] }, { "id": "benchmark", "label": "Benchmark", "tool": "", "logos": [], "glyph": "compare", "x": 980, "y": 820, "w": 150, "h": 56, "kind": "part", "desc": "A comparison of the design against a reference on the same criteria, with identifying labels removed so judgment is not biased by authorship. Criteria include hierarchy, legibility, interaction cost, and visual quality. The result is a ranked list of deficiencies.", "views": {}, "checks": [ "CRIT-3" ], "prompts": [ "p-CRIT-3" ], "env": [ "same", "" ] }, { "id": "exploration", "label": "Exploration", "tool": "", "logos": [], "glyph": "grid", "x": 1145, "y": 820, "w": 150, "h": 56, "kind": "part", "desc": "Generating several distinct design options before committing: sketches, wireframes, concept art, and variants on the real screen, compared side by side. Varying one property at a time attributes each difference in quality to a specific change.", "views": {}, "checks": [ "EXP-1", "EXP-2", "EXP-3" ], "prompts": [ "p-EXP-1", "p-EXP-2", "p-EXP-3" ], "env": [ "same", "" ] }, { "id": "usability", "label": "Usability test", "tool": "", "logos": [], "glyph": "person", "x": 485, "y": 820, "w": 150, "h": 56, "kind": "part", "desc": "Observation of representative users attempting real tasks without assistance, often while thinking aloud. Hesitations, errors, and questions locate design problems. Nielsen and Landauer found that about five users reveal most usability problems in a design.", "views": {}, "checks": [ "CRIT-4" ], "prompts": [ "p-CRIT-4" ], "env": [ "same", "" ] }, { "id": "system", "label": "Design system", "tool": "", "logos": [], "glyph": "book", "x": 320, "y": 820, "w": 150, "h": 56, "kind": "part", "desc": "The documented standards a product is built from: design tokens (color, type, spacing), components, and usage guidelines. Findings from critique are recorded here, including in agent instructions such as AGENTS.md or a design skill, so later screens and agents apply them.", "views": {}, "checks": [ "CRIT-5" ], "prompts": [ "p-CRIT-5" ], "env": [ "same", "" ] } ], "edges": [ { "id": "goal-screen", "from": "goal", "to": "screen", "path": "dep", "pts": [ [ 234, 230 ], [ 264, 230 ], [ 264, 380 ], [ 520, 380 ] ], "label": "requirements", "labelAt": [ 392, 380 ] }, { "id": "context-screen", "from": "context", "to": "screen", "path": "dep", "pts": [ [ 234, 282 ], [ 264, 282 ], [ 264, 380 ], [ 520, 380 ] ] }, { "id": "refs-screen", "from": "refs", "to": "screen", "path": "dep", "pts": [ [ 234, 334 ], [ 264, 334 ], [ 264, 380 ], [ 520, 380 ] ] }, { "id": "decompose-screen", "from": "decompose", "to": "screen", "path": "dep", "pts": [ [ 234, 386 ], [ 264, 386 ], [ 264, 380 ], [ 520, 380 ] ] }, { "id": "ia-screen", "from": "ia", "to": "screen", "path": "dep", "pts": [ [ 234, 438 ], [ 264, 438 ], [ 264, 380 ], [ 520, 380 ] ] }, { "id": "screen-hierarchy", "from": "screen", "to": "hierarchy", "path": "req", "pts": [ [ 600, 335 ], [ 600, 165 ], [ 96, 165 ], [ 96, 110 ] ] }, { "id": "screen-contrast", "from": "screen", "to": "contrast", "path": "req", "pts": [ [ 600, 335 ], [ 600, 165 ], [ 258, 165 ], [ 258, 110 ] ] }, { "id": "screen-gestalt", "from": "screen", "to": "gestalt", "path": "req", "pts": [ [ 600, 335 ], [ 600, 165 ], [ 420, 165 ], [ 420, 110 ] ] }, { "id": "screen-layout", "from": "screen", "to": "layout", "path": "req", "pts": [ [ 600, 335 ], [ 600, 165 ], [ 582, 165 ], [ 582, 110 ] ], "label": "composition", "side": "right", "labelAt": [ 600, 250 ] }, { "id": "screen-iconography", "from": "screen", "to": "iconography", "path": "req", "pts": [ [ 700, 335 ], [ 700, 165 ], [ 767, 165 ], [ 767, 110 ] ], "label": "representation", "side": "right", "labelAt": [ 700, 250 ] }, { "id": "screen-dataviz", "from": "screen", "to": "dataviz", "path": "req", "pts": [ [ 700, 335 ], [ 700, 165 ], [ 955, 165 ], [ 955, 110 ] ] }, { "id": "screen-copy", "from": "screen", "to": "copy", "path": "req", "pts": [ [ 700, 335 ], [ 700, 165 ], [ 1155, 165 ], [ 1155, 110 ] ] }, { "id": "screen-typography", "from": "screen", "to": "typography", "path": "req", "pts": [ [ 520, 470 ], [ 294, 470 ], [ 294, 530 ], [ 234, 530 ] ], "label": "style", "labelAt": [ 410, 470 ] }, { "id": "screen-color", "from": "screen", "to": "color", "path": "req", "pts": [ [ 520, 470 ], [ 294, 470 ], [ 294, 592 ], [ 234, 592 ] ] }, { "id": "screen-artdirection", "from": "screen", "to": "artdirection", "path": "req", "pts": [ [ 520, 470 ], [ 294, 470 ], [ 294, 654 ], [ 234, 654 ] ] }, { "id": "screen-motion", "from": "screen", "to": "motion", "path": "req", "pts": [ [ 520, 470 ], [ 294, 470 ], [ 294, 716 ], [ 234, 716 ] ] }, { "id": "screen-affordance", "from": "screen", "to": "affordance", "path": "req", "pts": [ [ 780, 420 ], [ 1000, 420 ], [ 1000, 280 ], [ 1083, 280 ] ], "label": "interaction", "labelAt": [ 890, 420 ] }, { "id": "screen-feedforward", "from": "screen", "to": "feedforward", "path": "req", "pts": [ [ 780, 420 ], [ 1000, 420 ], [ 1000, 350 ], [ 1083, 350 ] ] }, { "id": "screen-disclosure", "from": "screen", "to": "disclosure", "path": "req", "pts": [ [ 780, 420 ], [ 1000, 420 ], [ 1083, 420 ] ] }, { "id": "screen-feedback", "from": "screen", "to": "feedback", "path": "req", "pts": [ [ 780, 420 ], [ 1000, 420 ], [ 1000, 490 ], [ 1083, 490 ] ] }, { "id": "screen-states", "from": "screen", "to": "states", "path": "req", "pts": [ [ 780, 420 ], [ 1000, 420 ], [ 1000, 560 ], [ 1083, 560 ] ] }, { "id": "screen-squint", "from": "screen", "to": "squint", "path": "fb", "pts": [ [ 650, 505 ], [ 650, 792 ] ], "label": "review", "side": "right", "labelAt": [ 650, 700 ] }, { "id": "squint-slop", "from": "squint", "to": "slop", "path": "fb", "pts": [ [ 725, 820 ], [ 740, 820 ] ] }, { "id": "slop-benchmark", "from": "slop", "to": "benchmark", "path": "fb", "pts": [ [ 890, 820 ], [ 905, 820 ] ] }, { "id": "benchmark-exploration", "from": "benchmark", "to": "exploration", "path": "fb", "pts": [ [ 1055, 820 ], [ 1070, 820 ] ] }, { "id": "exploration-screen", "from": "exploration", "to": "screen", "path": "fb", "pts": [ [ 1145, 792 ], [ 1145, 745 ], [ 740, 745 ], [ 740, 505 ] ], "label": "iteration", "labelAt": [ 940, 745 ] }, { "id": "squint-usability", "from": "squint", "to": "usability", "path": "fb", "pts": [ [ 575, 820 ], [ 560, 820 ] ] }, { "id": "usability-system", "from": "usability", "to": "system", "path": "fb", "pts": [ [ 410, 820 ], [ 395, 820 ] ] }, { "id": "system-screen", "from": "system", "to": "screen", "path": "fb", "pts": [ [ 320, 792 ], [ 320, 745 ], [ 560, 745 ], [ 560, 505 ] ], "label": "standards", "labelAt": [ 440, 745 ] } ], "zones": [ { "id": "composition", "label": "composition", "x": 10, "y": 20, "w": 658, "h": 118 }, { "id": "representation", "label": "representation", "x": 677, "y": 20, "w": 590, "h": 118, "labelRight": true }, { "id": "research", "label": "research", "x": 8, "y": 196, "w": 234, "h": 274 }, { "id": "style", "label": "style", "x": 8, "y": 496, "w": 234, "h": 254 }, { "id": "interaction", "label": "interaction", "x": 1070, "y": 244, "w": 236, "h": 352, "labelRight": true }, { "id": "critique", "label": "critique", "x": 232, "y": 778, "w": 1002, "h": 86 } ], "tours": { "req": { "label": "a warehouse sim", "steps": [ { "edge": "screen-dataviz", "text": "A warehouse simulation shows robots, racks, and remote pilots. Each pilot is encoded as one colored icon, replacing the text \"Pilot P1\" repeated in five places." }, { "edge": "screen-hierarchy", "text": "The factory floor is the focal point. The order queue gains emphasis only when an order is late." }, { "edge": "screen-gestalt", "text": "Panels are grouped by proximity on a shared grid, without titled boxes or section numbers." }, { "edge": "screen-copy", "text": "Robot names and exact counts remain as text. The label \"01 Pick Floor\" is removed, because the rack graphics identify the pick floor." }, { "edge": "screen-affordance", "text": "Pause, reset, and speed use conventional symbols (⏸ ⟲ ▸ ▸▸ ▸▸▸), and each control appears once." }, { "edge": "screen-disclosure", "text": "A robot's statistics open in an inspector when it is selected, replacing a permanent sidebar." }, { "edge": "screen-feedback", "text": "Assigning a pilot recolors the robot immediately and plays a sound." } ] }, "dep": { "label": "the requirements", "steps": [ { "edge": "goal-screen", "text": "User goal: decide which robot needs a pilot next." }, { "edge": "context-screen", "text": "Context of use: the last speed and layout are restored at launch." }, { "edge": "refs-screen", "text": "References: the interfaces of established factory-building games." }, { "edge": "decompose-screen", "text": "Decompose: the best reference's panel widths, type scale, and colors are read from its files and recorded." }, { "edge": "ia-screen", "text": "Information architecture: the pilot count appears once, on the pilots themselves." } ] }, "fb": { "label": "one iteration", "steps": [ { "edge": "screen-squint", "text": "Squint test: the eye lands on the title bar instead of the floor." }, { "edge": "squint-slop", "text": "Slop audit: section numbers, a duplicated \"unofficial demo\" notice, and a panel restating the floor are removed." }, { "edge": "slop-benchmark", "text": "Benchmark: beside the reference, the side panels carry more visual weight than the floor." }, { "edge": "benchmark-exploration", "text": "Exploration: four side-panel variants on the real screen; a compact context bar is chosen." }, { "edge": "exploration-screen", "text": "The chosen variant is implemented." }, { "edge": "squint-usability", "text": "Usability test: a new player cannot find the speed controls." }, { "edge": "usability-system", "text": "Design system: the guideline that controls sit within the player's existing focus is recorded." }, { "edge": "system-screen", "text": "The next screen is designed from the updated guideline." } ] } }, "prompts": { "p-RES-1": { "id": "p-RES-1", "title": "Define the user goal", "stage": 1, "checks": [ "RES-1" ], "primary": true, "body": "I want this screen built around the one thing a person comes to it to do. If it isn't clear which screen, ask me.\n\nWork out what someone is here to learn, decide, or do, from the project and how the screen is used; ask me only if you truly can't tell. The classic failure is a screen that serves five purposes equally, so nothing stands out. Give that purpose the most size, contrast, and the best position, quiet what only supports it, and move out what belongs elsewhere.\n\nCommit the current state first so we can go back. Then make the improvements, and show me before and after side by side, with the purpose in one sentence and the reason for each change. I'll give feedback and we'll iterate. Once I'm happy, tell me which other screens have the same problem, and ask before changing them." }, "p-RES-2": { "id": "p-RES-2", "title": "Infer from the context of use", "stage": 1, "checks": [ "RES-2" ], "primary": true, "body": "I want this screen to ask the person for less, by using what it already knows. If it isn't clear which screen, ask me.\n\nFor every choice and input it asks for, check whether the answer could come from context: the time, the place, the device, the last setting they chose, what they did a moment ago, or what most people choose. The classic failure is software that wakes up every day with amnesia and makes people repeat themselves. Look at how the best apps in this category handle defaults and memory, and at what the project already stores. Don't start collecting new personal data without asking me.\n\nCommit the current state first so we can go back. Then remove or pre-fill every question the evidence supports, and show me before and after, with where each answer now comes from and the count of questions left. I'll give feedback and we'll iterate. Once I'm happy, point out other screens that ask for things they could know, and ask before changing them." }, "p-RES-3": { "id": "p-RES-3", "title": "Collect references", "stage": 1, "checks": [ "RES-3" ], "primary": true, "body": "I want this screen to borrow its structure from an expert screen that already solves the same task, instead of a layout invented from scratch. If it isn't clear which screen, ask me.\n\nFind three to five excellent references for the same job, from shipped products and games rather than concept shots; the Game UI Database is a good source for games, Mobbin for apps. Choose the one whose information structure fits my task best: what's biggest, what's grouped, what's hidden until needed. Copy that structure, not its look: keep my own style, content, and world, and leave out anything that doesn't fit.\n\nCommit the current state first so we can go back. Then rebuild the screen on that structure, and show me my old screen, the reference, and the new version side by side, with what you borrowed and why, and the other references in case I prefer one. I'll give feedback and we'll iterate." }, "p-RES-4": { "id": "p-RES-4", "title": "Decompose a reference", "stage": 1, "checks": [ "RES-4" ], "primary": true, "body": "I want an exact technical reference for a design that already achieves the effect I'm after, so we can remix it instead of guessing. If it isn't clear which design or which part of it, ask me.\n\nGet its real source rather than working from screenshots: search GitHub for published code, read a live site's HTML, styles, and scripts in the browser, and for apps without published source use REA (github.com/morluto/rea). Record every design choice with its exact value: grid and spacing, type scale, palette, shadows and radii, each animation's duration and easing, every state. Say why each one works. Learn the technique, not the identity: logos, images, copy, and brand stay theirs.\n\nCommit the current state first so we can go back. Then rebuild the design from your record alone and show it beside the original; wherever they differ, the record is missing something, so fix it. Then show me which choices carry the effect and how you'd remix them into my project. I'll give feedback and we'll iterate." }, "p-RES-5": { "id": "p-RES-5", "title": "Inventory the content", "stage": 1, "checks": [ "RES-5" ], "primary": true, "body": "I want to know everything this screen shows or lets someone do, and to clear out what doesn't belong. If it isn't clear which screen, ask me.\n\nGo through the screen and the code behind it, and list every fact, number, label, and action, with where each appears and how often. The classic finding is the same number or button in three or four places. Decide for each whether it serves the screen's main purpose: keep it, move it somewhere better (a tooltip, a panel, another screen), or remove it. Keep anything someone needs before an irreversible decision in view.\n\nCommit the current state first so we can go back. Then make the moves and removals, and show me before and after side by side, with the list and the reason for each call beside them so I can overrule any. Save the list with the project's design notes, if it has any. I'll give feedback and we'll iterate." }, "p-RES-6": { "id": "p-RES-6", "title": "Give each item one location", "stage": 1, "checks": [ "RES-6" ], "primary": true, "body": "I want every fact and every action on this screen to have exactly one home. If it isn't clear which screen, ask me.\n\nFind everything that appears more than once: the same count in several panels, the same button in two places, a name in a heading and again in a label. There may already be a list of the screen's contents somewhere; check first. Edward Tufte's principle \"erase redundant data-ink\" names the problem: a fact shown twice costs attention twice and informs once. Give each its single best home, usually on the thing it describes. Several cues in that one home (a color and an icon) are fine.\n\nCommit the current state first so we can go back. Then remove the duplicates, and show me before and after side by side, with each duplicate, the home you kept, and the count removed. I'll give feedback and we'll iterate. Once I'm happy, check the rest of the app for the same duplication, and ask before changing other screens." }, "p-EXP-1": { "id": "p-EXP-1", "title": "Wireframe before styling", "stage": 2, "checks": [ "EXP-1" ], "primary": true, "body": "Before any styling, I want the simplest working version of this screen: plain controls, real content, and the right structure. If it isn't clear what we're building, ask me.\n\nBuild a wireframe: ordinary buttons and text, no colors or decoration, but the real data, the real actions, and the layout we expect to keep. The point is to see whether the task works before we fall in love with a look. The classic failure is decorating a layout that was never going to work.\n\nBuild it alongside the real screen, not over it, and open it for me. Do the main task on it yourself, then fix what that revealed: anything missing, anything we don't need, anything confusing even without styling. Show me the first and the fixed wireframe side by side, with what each fix solved. I'll try it and we'll iterate." }, "p-EXP-2": { "id": "p-EXP-2", "title": "Generate concept art", "stage": 2, "checks": [ "EXP-2" ], "primary": true, "body": "Before we write more interface code, I want concept art of the finished screen, so we choose a direction by looking. If it isn't clear which screen, ask me.\n\nUse whatever image generation this setup has. Make three or four genuinely different directions of the whole screen, as if each were a screenshot of a finished, beautiful product: real content and layout, with no slogans, labels, or titles added for the picture. Use any references or style we like, and the layout of an expert screen where it fits.\n\nShow them side by side. I'll say which I prefer and why, and you'll push that direction for another round; we'll keep going until one is right. Save the prompts and images with the project. When we've chosen, build the screen to match on a fresh commit, and show me the concept and the result side by side." }, "p-EXP-3": { "id": "p-EXP-3", "title": "Compare variants", "stage": 2, "checks": [ "EXP-3" ], "primary": true, "body": "I want to find the best version of this screen by comparing many, rather than accepting the first. If it isn't clear which screen or part of it, ask me.\n\nMake four to six genuinely different versions with the same content: different hierarchy, layouts, or representations, not small variations of one idea. Put them side by side on one simple local page and open it for me, with no explanation around them, so the designs speak for themselves.\n\nI'll tell you what I like. Then make a new round that pushes further in that direction, changing one thing at a time so we can see what each change does, and keep every round on the page. When we've chosen, build the winner into the real screen on a fresh commit, show me before and after, and save the reasons we chose it where my agents will read them next time." }, "p-COMP-1": { "id": "p-COMP-1", "title": "Set the hierarchy", "stage": 3, "checks": [ "COMP-1" ], "primary": true, "body": "I want the eye to go to the right place first on this screen, and then in the right order. If it isn't clear which screen, ask me.\n\nRank everything on it: critical (seen in a fraction of a second), glanceable, and reference. The eye goes first to the brightest, largest, most contrasting thing, so size, contrast, color, and weight should follow that ranking. Passive information should only get louder when it changes or needs attention. Nielsen's heuristic 8 explains the classic failure, everything at the same weight: every extra unit of information competes with the relevant ones and diminishes their visibility.\n\nCommit the current state first so we can go back. Make the changes, and show me before and after, both normal and blurred, so we can see where the eye lands, with the ranking beside them. I'll give feedback and we'll iterate. Once I'm happy, suggest how the same ranking could become shared styles across the app, and ask before changing other screens." }, "p-COMP-2": { "id": "p-COMP-2", "title": "Group by Gestalt principles", "stage": 3, "checks": [ "COMP-2" ], "primary": true, "body": "I want this screen grouped and aligned cleanly, using space instead of boxes. If it isn't clear which screen, ask me.\n\nThings that belong together should sit close together, and groups should be separated by space before borders, boxes, or dividers. Things should share a few edges rather than each sitting on its own, a heading shouldn't look like the items under it, and readable content should sit on a plain background. The classic failure is cards inside cards, five borders on one button, and many slightly different left edges. In Tufte's terms most of those borders are non-data-ink: Gestalt proximity and common region already do the grouping.\n\nCommit the current state first so we can go back. Regroup the screen, and show me before and after side by side, with the number of borders and distinct left edges in each. I'll give feedback and we'll iterate. Once I'm happy, suggest how to carry the spacing into the app's shared styles, and ask before changing other screens." }, "p-COMP-3": { "id": "p-COMP-3", "title": "Test the layout at every size", "stage": 3, "checks": [ "COMP-3" ], "primary": true, "body": "I want this screen to look carefully made at every size. If it isn't clear which screen, ask me.\n\nLook for the craft problems that make things look unprofessional: overlapping elements, clipped or squashed text, stretched images, things that should be centered but aren't, and edges that almost line up. Try the hardest cases: the longest names, the biggest numbers, every error, a phone, a laptop, and a wide monitor. The classic failure is a screen that only works with the demo data at one size.\n\nCommit the current state first so we can go back. Take screenshots at those sizes, fix every defect you find, and show me before and after for each fix. Then set up the simplest automatic check this project can keep running, such as screenshots at several sizes or an overlap check, so the defects don't come back. I'll give feedback and we'll iterate." }, "p-REP-1": { "id": "p-REP-1", "title": "Use conventional symbols", "stage": 4, "checks": [ "REP-1" ], "primary": true, "body": "I want this screen to show things instead of saying them. If it isn't clear which screen, ask me.\n\nFor every piece of text, ask whether a picture could carry the meaning: the thing's own appearance (a rack that looks like a rack), a standard convention (pause, play, a clipboard for copy), a position, or a color backed by a shape. Keep words where a picture would be a puzzle: names, exact values, and anything the person commits to, like Buy. Don Norman's rule of thumb in The Design of Everyday Things: when simple things need labels or instructions, the design has failed. A symbol that needs a legend is an instruction too.\n\nCommit the current state first so we can go back. Make the replacements, and show me before and after side by side, with the convention behind each one, and flag anything a first-time user might no longer understand. I'll give feedback and we'll iterate. Once I'm happy, suggest where the same symbols belong across the app, and ask before changing other screens." }, "p-REP-2": { "id": "p-REP-2", "title": "Encode quantities graphically", "stage": 4, "checks": [ "REP-2" ], "primary": true, "body": "I want the numbers on this screen to be readable at a glance. If it isn't clear which screen, ask me.\n\nFind every number and repeated item. Small counts (under about ten) usually read faster as pips or tallies, which can also carry color; values to compare read best as bars on one shared scale; large exact values stay numbers, with a unit icon. Repeated things, like players or pilots, can each get one recognizable icon used everywhere, with the full name in a tooltip. Cleveland and McGill found position on a common scale the most accurately read encoding, and Tufte's data-ink ratio asks that ink carry data. Look at how games and dashboards known for clarity show this kind of data.\n\nCommit the current state first so we can go back. Make the changes, and show me before and after side by side, with the reason for each representation. I'll give feedback and we'll iterate. Once I'm happy, suggest where the same representation belongs across the app, and ask before changing other screens." }, "p-REP-3": { "id": "p-REP-3", "title": "Apply the five text tests", "stage": 4, "checks": [ "REP-3" ], "primary": true, "body": "I want every string on this screen to pass five published tests, so the text that remains is there for a reason we can name. If it isn't clear which screen, ask me.\n\nThe tests: redundancy (Edward Tufte: \"erase redundant data-ink\"; does the screen already show this?), instruction (Don Norman: when simple things need labels or instructions, the design has failed; Steve Krug: \"instructions must die\"), happy talk (Krug: text that says nothing specific), relevance (Nielsen's heuristic 8: \"every extra unit of information competes with the relevant units of information\"), and self-identification (Refactoring UI: \"labels are a last resort\"). Read the originals if you can.\n\nCommit the current state first so we can go back. Then fix every string that fails: delete it, move it behind a tooltip or panel, or change the design so it isn't needed. Show me before and after side by side, with each removal and the test it failed, so I can bring any back. I'll give feedback and we'll iterate. Once I'm happy, offer to run the same tests across the app, and ask before changing other screens." }, "p-INT-1": { "id": "p-INT-1", "title": "Make affordances visible", "stage": 5, "checks": [ "INT-1" ], "primary": true, "body": "I want the actions on this screen to be obvious, direct, and each in one place. If it isn't clear which screen, ask me.\n\nGood actions work directly on the thing they change (drag the item, click the robot), look pressable while information looks printed, and appear once. Standard symbols beat words for standard actions. Don Norman's terms help: signifiers show where to act, and mapping relates a control to what it changes. The classic failures are the same action in two places, buttons far from what they affect, and things that look clickable but do nothing. Look at how the best products in this category place their actions.\n\nCommit the current state first so we can go back. Make the changes, check that everything that looks pressable does something, and show me before and after side by side, with the reason for each move. I'll give feedback and we'll iterate. Once I'm happy, suggest where the same pattern applies across the app, and ask before changing other screens." }, "p-INT-2": { "id": "p-INT-2", "title": "Add feedforward", "stage": 5, "checks": [ "INT-2" ], "primary": true, "body": "Before someone commits to an action on this screen, I want them to see what will actually happen. If it isn't clear which screen, ask me.\n\nFind the actions that cost something or can't easily be undone: spending, replacing, deleting, sending, assigning. For each, work out the consequence that matters to that decision (what's left afterwards, what changes, what gets replaced) and show it before they commit, ideally right where they're looking. The classic failure is a price or a button with no hint of the result, and the opposite, a spreadsheet of every possible consequence.\n\nCommit the current state first so we can go back. Add the previews, try each with test data rather than real accounts, and check that every preview matches what really happens. Show me each action before and after. I'll give feedback and we'll iterate. Once I'm happy, suggest other places in the app that need the same preview, and ask before changing them." }, "p-INT-3": { "id": "p-INT-3", "title": "Apply progressive disclosure", "stage": 5, "checks": [ "INT-3" ], "primary": true, "body": "I want this screen to show an overview first and details only when someone asks. If it isn't clear which screen, ask me.\n\nFind the explanations and secondary data that sit on the screen permanently: help text, stat panels, descriptions. Each could open from the thing it describes instead: a tooltip, an inspector that opens on click, or a small context bar. Tooltips should work with hover, keyboard focus, and touch. The main task must work without opening any of them, so prices, warnings, and the main actions never live only in a tooltip. The sources are Nielsen's heuristic 8 (no information that is irrelevant or rarely needed) and Shneiderman's mantra (overview first, zoom and filter, then details on demand).\n\nCommit the current state first so we can go back. Move the details, and show me before and after, the main task done without opening anything, and the details on demand. I'll give feedback and we'll iterate. Once I'm happy, suggest a shared tooltip or inspector pattern for the app, and ask before changing other screens." }, "p-INT-4": { "id": "p-INT-4", "title": "Give every action feedback", "stage": 5, "checks": [ "INT-4" ], "primary": true, "body": "I want every action on this screen to answer back, so it never feels like nothing happened. If it isn't clear which screen, ask me.\n\nGood feedback is immediate (within about a tenth of a second), uses at least two channels (a visual change plus sound or motion), shows cause before effect, plays one thing at a time, and scales with how much the moment matters. Motion should show where something went. The classic failures are silent clicks, and the opposite: every click flashing and bouncing the same. Look at what makes feedback feel good in games and apps of this kind.\n\nCommit the current state first so we can go back. Add or fix the feedback for every action, make sure nothing fires twice, and show me a short recording of each before and after. I'll give feedback and we'll iterate. Once I'm happy, suggest how to make the best of it shared across the app, and ask before changing other screens." }, "p-INT-5": { "id": "p-INT-5", "title": "Design every state", "stage": 5, "checks": [ "INT-5" ], "primary": true, "body": "I want every state of this screen designed, not just the one with perfect data. If it isn't clear which screen, ask me.\n\nFind the states it can be in: empty, loading, partial, too much data, and each kind of error. An empty state is a chance to show what to do first; an error says what went wrong and how to fix it, without apologizing or narrating. The classic failure is a screen that looks broken whenever the data isn't ideal.\n\nCommit the current state first so we can go back. Design and build each state, force each one with test data, and show me a screenshot of every state before and after. I'll give feedback and we'll iterate. Once I'm happy, suggest shared empty, loading, and error components for the rest of the app, and ask before changing other screens." }, "p-STYLE-1": { "id": "p-STYLE-1", "title": "Define the art direction", "stage": 6, "checks": [ "STYLE-1" ], "primary": true, "body": "I want this screen to look like it belongs to one coherent world, with one tone. If it isn't clear which screen or project, ask me.\n\nA good style derives its parts from what that world is made of (paper, brass, glass, pixels) rather than putting a theme sticker on a generic rectangle. Keep containers consistent and let their contents vary. The classic failures are mixed styles (flat clip-art in a painted world, modern type in a period setting) and ornament everywhere, so nothing stands out. Describe the world, its materials, and what to avoid in a few lines, from the project and anything we've said.\n\nCommit the current state first so we can go back. Then change every frame, button, border, icon, and font that doesn't fit, and show me before and after side by side, with the description beside them. I'll give feedback and we'll iterate. Once I'm happy, suggest how to apply it to the rest of the app through its shared styles, and ask before changing other screens." }, "p-STYLE-2": { "id": "p-STYLE-2", "title": "Define typography and color", "stage": 6, "checks": [ "STYLE-2" ], "primary": true, "body": "I want the type and color on this screen to each do a job. If it isn't clear which screen, ask me.\n\nFor type, the usual strong setup is two roles: a display face with character for names and titles, and a plain, highly legible face for numbers and rules, with digits that line up. For color, each color should mean one thing everywhere (a state, a team, a resource) and be backed by a second cue like shape or icon. The classic failures are decorative color that means nothing, one color meaning three things, and contrast that only works over some of the art.\n\nCommit the current state first so we can go back. Set up a small type and color system, apply it to this screen, and show me before and after plus a grayscale screenshot. Measure contrast on the real screen, not just the color values. I'll give feedback and we'll iterate. Once I'm happy, suggest how to make it the app's shared type and color, and ask before changing other screens." }, "p-CRIT-1": { "id": "p-CRIT-1", "title": "Run a squint test", "stage": 7, "checks": [ "CRIT-1" ], "primary": true, "body": "I want to test whether this screen reads at a glance, and fix it if it doesn't. If it isn't clear which screen, ask me.\n\nTake a screenshot and look at it three ways: blurred, in grayscale, and for about one second. In each, where does the eye land first, second, and third, and does that match what matters most? In grayscale, does any meaning disappear because only color carried it? The classic finding is that the eye goes to decoration, a title, or a panel instead of the thing the person came to do.\n\nCommit the current state first so we can go back. Fix the most important problem, then show me all three views before and after, with your honest read of each. I'll give feedback and we'll iterate." }, "p-CRIT-2": { "id": "p-CRIT-2", "title": "Run a slop audit", "stage": 7, "checks": [ "CRIT-2" ], "primary": true, "body": "I want a slop audit of this screen: the conventions AI-generated interfaces default to, removed in a deletion pass. If it isn't clear which screen, ask me.\n\nEach common habit fails a published test. Eyebrow labels, subtitles that restate a title, duplicated counts, numbering on things that aren't a sequence, and status narration (\"5 recorded\", \"Ready\") are redundant data-ink in Edward Tufte's sense: they repeat what the screen already shows. Explanations of the screen and usage hints are instructions, which Don Norman treats as a sign the design failed and Steve Krug says \"must die.\" Taglines and feature blurbs are what Krug calls happy talk. Nested borders and glow that mean nothing are non-data-ink.\n\nCommit the current state first so we can go back. Then remove each element in turn, and restore only what passes. Keep precise words where no conventional symbol exists; a symbol that needs a legend is an instruction in disguise. Show me before and after side by side, with each removal and the test it failed, so I can bring any back. I'll give feedback and we'll iterate. Once I'm happy, offer to run the same pass across the app, and ask before changing other screens." }, "p-CRIT-3": { "id": "p-CRIT-3", "title": "Benchmark against the reference", "stage": 7, "checks": [ "CRIT-3" ], "primary": true, "body": "I want this screen to hold up against the expert screen it should be as good as. If it isn't clear which screen or which reference, ask me.\n\nPut screenshots of my screen and the reference side by side, without labels, and judge them the way a demanding art director would: hierarchy, clarity at a glance, how actions read, feedback, style, and craft. Assume mine is worse until shown otherwise; a tie counts as a loss. The classic failure is a review that only lists what's good.\n\nCommit the current state first so we can go back. Fix the single most damaging flaw, then show me the reference, my old screen, and the new one side by side, with your verdict on each point and the evidence for it. I'll give feedback, and we'll keep fixing the next-worst flaw until mine wins." }, "p-CRIT-4": { "id": "p-CRIT-4", "title": "Run a usability test", "stage": 7, "checks": [ "CRIT-4" ], "primary": true, "body": "I want to learn what's confusing about this screen by watching someone use it, not by asking my agent. If it isn't clear which screen, ask me.\n\nGive me what I need to run a short session today: one or two realistic tasks for a person who's never seen it, the few words I should say (almost nothing), and a one-page note sheet for every hesitation, misread, wrong click, and question. Five people usually find most of the problems; one is far better than none. The classic failure is helping them, which hides exactly the problems we need to see.\n\nAfter the session I'll tell you what happened. Then, on a fresh commit, fix the three problems that hurt most, treating each as a design problem rather than a user mistake, and show me before and after for each, with what you observed that caused it." }, "p-CRIT-5": { "id": "p-CRIT-5", "title": "Update the design system", "stage": 7, "checks": [ "CRIT-5" ], "primary": true, "body": "I want what we've learned on this screen to improve the whole app, not just this one screen.\n\nLook back at the design changes we've made recently, in this conversation or the project's history, and find the ones that made the biggest difference. Then look across the app for the same problems, and for the shared styles, components, or tokens where one fix would reach every screen at once. The classic failure is a lesson that lives in one screen while every other screen keeps the old mistake.\n\nThis changes screens I haven't looked at, so talk it through with me first: which improvements you'd apply where, and which screens they might not suit, made concrete from what you know about the project. Then, on a fresh commit, apply what I agree to, and show me before and after of every screen it touched. Record each principle in a sentence or two, with its before and after, wherever my agents will read it: a design notes file, the project's agent instructions (a file like AGENTS.md), or a design skill. Check what exists first." } }, "legend": { "req": "design", "dep": "research", "fb": "critique" } }