diff --git a/AGENTS.md b/AGENTS.md index 75eb6870a5..f2bdb8fbdd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -324,6 +324,15 @@ create new approval gates. Distinguish proposed, packaged and installed behavior ## UI Design Standard +**Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.** +Use hierarchy, grouping, spacing and clear control names to make the interface +understandable. Remove slogans, heading restatements and implementation or Agent +instructions from product UI. Improve unclear layout before adding explanatory +paragraphs. Preserve accessible control names, necessary input constraints, +permission and activation consequences, errors, recovery and action outcomes; +place optional help on demand. Apply this in the whole-page visual review, +not only to isolated components or by imposing a blanket text-length limit. + Before changing or reproducing any UI (including websites, dashboards, desktop, documentation, prototypes, screenshots or framework migrations), read [the design system](docs/development/design.md), especially diff --git a/docs/development/design.md b/docs/development/design.md index 15bea6904a..f5edb4380e 100644 --- a/docs/development/design.md +++ b/docs/development/design.md @@ -148,6 +148,19 @@ size empty summaries to their content rather than filling large decorative cards ### Explanations On Demand +Make layout explain the interface before adding secondary copy. Hierarchy, +grouping, spacing and clear control names should reveal what belongs together +and what can be done. Remove decorative slogans, subtitles that repeat headings, +instructions that restate visible controls, and implementation or Agent-facing +directions. When a paragraph compensates for unclear layout, redesign that layout +first. This applies across the page, not only inside one component. It does not +remove accessible control names, necessary input constraints, permission or +activation consequences, errors, recovery or action outcomes. Keep optional help +at the existing contextual entry; a blanket word limit cannot judge its value. +This distinction follows the [layout-first copy observation](https://x.com/luinlee/status/2113085361836744764) +and the [author's explanation](https://x.com/luinlee/status/2113085363606765963); +those observations motivate the rule, not a measured model-quality guarantee. + The primary view presents the result, its unit and scope, material uncertainty, and the next useful action. A truthful interface does not need to repeat its methodology in every component. Review the whole viewport for repeated scope, @@ -666,8 +679,10 @@ parity is required. Framework migration alone must not alter the UI. - [ ] Marketing and application controls use the correct shape language. - [ ] Desktop and mobile layouts are validated. - [ ] Keyboard, focus, contrast, and reduced-motion behavior are preserved. -- [ ] Repeated explanations are consolidated; help works on hover, focus and tap, - while material qualifiers, failures and action consequences remain visible. +- [ ] Layout and control names explain the task without slogans, repeated labels + or instructions about the implementation. Necessary labels, qualifiers, + failures and action consequences remain visible; optional help works on + hover, focus and tap. - [ ] Owner decisions complete in place with a readback; live treatment is backed by an observed active fact; protocol identifiers are not primary copy. - [ ] English and Chinese content remain usable.