Design Principles — ZCode

Design-to-delivery integration

For complex screen/feature design, consider design-to-delivery: an editable wireflow, brainstorming, linked spec and tasks help catch missing interactions, responsive states and implementation drift. Adapt or simplify that sequence to the task; a small UI change need not create a full design package. This skill supplies visual direction, responsive/RTL guidance and interaction details to the selected artifacts without a second plan. Preserve existing design documents and fulfill explicitly requested artifacts.

Purpose

Operate like an engineer who owns the product's design system — not a designer decorating a screenshot. The interface must feel intentional, readable, calm, and production-ready. This is the full playbook behind the compact User Design Standards rule in the global AGENTS.md.

When to use

Load when:

• Creating UI or modifying visual components (pages, components, themes, layouts).
• RTL work (Persian, Arabic, Hebrew) or LTR work.
• Changing styles, themes, design tokens, typography, motion, accessibility, or responsive behavior.

Do not load for:

• Fixing an isolated CSS bug (a single color, spacing, or alignment value).
• Backend or frontend logic changes.
• API work, infrastructure work, or anything non-visual.

Preconditions

• Treat professional design as an observable quality target: clear task hierarchy, intentional typography/spacing, usable real-content layouts, appropriate density, complete relevant states and consistent responsive/theme/RTL behavior. A sparse or simple interface is valid when it serves the product; decoration and complexity are not proof of quality.
• If branding is absent, inspect local assets, documentation and any approved references, then use the intake in references/product-and-existing-ui.md. Do not invent a finished brand or adopt a generic template merely to avoid asking a material identity question. If identity is already known, reuse it without asking again.
• Keep existing design language and approved brand assets as the source of truth. Inspect light/dark logo variants, icon artwork and token definitions rather than copying another project's palette. Improving an existing UI does not authorize replacing its design system.

The global AGENTS.md may provide compact non-negotiable design rules. This skill provides the detailed workflow and reasoning behind them; it stands alone when that section is absent.

Workflow — how the agent executes

Run this loop in order before and while writing UI code:

1. Understand product, users, and the flow before touching code. Identify product type, target users, usage frequency, and emotional goal (see references/product-and-existing-ui.md). Understand what the user is trying to accomplish in each view: the primary task, what information is needed before the action, and what happens after it.
2. Inspect the existing project before creating anything. Check existing components, design tokens, spacing system, typography scale, icon library, and interaction patterns (see references/product-and-existing-ui.md).

3. Resolve ambiguity before implementation. If the design goal, user intent, or expected behavior is unclear, inspect existing patterns and ask — do not guess major UX decisions. They are not cheap to reverse.

   Do not ask the user about existing patterns — inspect the project yourself. Do not ask about minor spacing choices or obvious implementation details. Ask before deciding: navigation changes, a new design language, user flow changes, or data hierarchy changes.

4. Reuse first, create second. Implement using existing patterns, components, and tokens. Introduce a new component, token, or pattern only when no existing one solves the problem.
5. Match surrounding idiom. Same component library, same tokens, same spacing rhythm, same file structure as the code you are extending — never a parallel style.
6. Validate before finishing. Load the design-validation skill and run its Final Design Review; fix anything it flags before calling the UI complete.

Before Redesigning

When the user asks to improve or review an existing UI ("this page doesn't look good"), diagnosing is the first task, not redesigning.

1. Identify the actual problem:
   • usability issue?
   • hierarchy issue?
   • consistency issue?
   • accessibility issue?
   • aesthetic preference?
2. Prefer targeted improvements over a full redesign.

Do not rewrite a working interface only because a different style looks modern. Report the diagnosis, then fix the identified problem — do not silently rebuild the page.

Core rules (always apply)

Intent first

The goal is not only visual beauty. The interface must feel intentional, readable, calm, and production-ready.

Prioritize:

1. Clarity over decoration
2. Consistency over novelty
3. Accessibility over visual effects
4. Meaningful design decisions over random creativity

Avoid:

• unnecessary visual noise
• excessive animations
• generic AI-generated layouts
• decoration without purpose

Calm and restraint are the default for daily-use productivity UI — not a limit on expressiveness. Marketing pages, landing pages, and campaigns may be bold and creative; match the interface to its purpose and context.

Long-Term Usage Principle

Interfaces are not screenshots. Optimize for:

• 8 hours of usage
• readability
• reduced eye strain
• consistent interaction

A beautiful UI that becomes tiring after 30 minutes is a bad UI. This is the primary difference between a real product design and an AI-generated mockup.

Avoid AI-Generated UI Patterns

Avoid the default patterns AI-generated UIs fall into:

• random glassmorphism
• excessive rounded cards
• gradient everywhere
• dashboards filled with meaningless cards
• fake statistics
• decorative icons without function

Every element must have a user purpose. If an element only exists to look modern, remove it or give it a function.

Large-Screen Space Usage (invariant)

Large screens must gain structure, not just whitespace.

Do not confuse centered narrow layouts with professional design. Do not center a narrow content column inside a large viewport unless the content is primarily long-form reading. Extra space must serve hierarchy, scanning, comparison, navigation, or task efficiency — wider workspaces, side navigation, contextual panels, filter rails, master-detail layouts, or multi-column grids. When useful, expand the layout structurally; do not merely enlarge margins. Full decision process: references/layout-responsive-and-information-architecture.md.

Information Architecture Before Grouping (invariant)

Do not group content only because items look visually similar, and do not create categories merely to make a page look organized. Before creating tabs, sections, filters, cards, accordions, or navigation groups, determine the user's task, which items are used together, what is primary versus supporting, and which groups represent real user concepts. Prefer the smallest number of meaningful groups; derive grouping from the user's mental model, never from a desired visual layout. Full decision process: references/layout-responsive-and-information-architecture.md.

Simplicity — do not over-engineer

Do not create abstractions only for theoretical reuse.

Create a component when it is:

• reused multiple times
• independent behavior worth isolating
• an improvement in readability

Avoid:

• premature design systems (tokens or abstraction layers invented for a single use)
• unnecessary wrapper components
• one-use abstractions
• "flexible" APIs with props nobody needs

The smallest change that satisfies the requirement is the target. A simple page with 3 components beats a "beautiful" architecture with 20.

Content integrity (invariant)

Never invent data to make a UI look complete — statistics, metrics, user data, testimonials, or product capabilities. Use placeholders only when explicitly requested or in a prototype, and always mark fictional content clearly. Full rules: references/content-and-performance.md.

Reference router — load only what the task touches

Before styling, read only the reference file(s) relevant to the task and apply those rules:

• Product type, target users, user flow, inspecting an existing design system → references/product-and-existing-ui.md
• Layout, spacing, whitespace, information density → references/layout-spacing-density.md
• Large-screen space usage, responsive layout, width strategy, navigation patterns, content grouping and categorization → references/layout-responsive-and-information-architecture.md
• RTL (Persian/Arabic/Hebrew) or LTR direction work → references/rtl-ltr.md
• Color system, tokens, themes, dark mode → references/color-system.md
• Typography sizing, type scales, readability, age-aware ergonomics, interaction sizing → references/typography-and-ergonomics.md
• Building or reusing components, component states, icons → references/components-and-states.md
• Motion, animation → references/motion-and-responsive.md
• Responsive behavior across viewport sizes → references/layout-responsive-and-information-architecture.md
• Accessibility (keyboard, focus, contrast, ARIA, reduced motion) → references/accessibility.md
• UI copy, product-level states, performance, documenting design decisions → references/content-and-performance.md

Common mistakes

• Introducing a new visual language when an existing design system exists.
• Creating abstractions, components, or token layers for theoretical reuse.
• Applying direction: rtl without mirroring layout and directional icons — the most common RTL bug.
• Pure #000 background with pure #FFF text in dark themes.
• Random colors without a token system.
• One-off components instead of reusing existing patterns.
• Generic AI-generated layouts or decoration without purpose.
• Rewriting a working interface in a new style when a targeted fix would do.
• Animations everywhere instead of on state changes/feedback.
• Using color alone to communicate state or meaning.
• Assuming mobile-first for a desktop productivity product.
• Shipping a design without running the final review.

Validation

For changed interactions, prove the affected user outcomes with the project E2E skill or e2e-test-authoring where appropriate. Static checks and screenshots complement functional tests; neither substitutes for the other. If rendered inspection is unavailable, report it as unverified instead of checking every visual item from code alone.

Before finishing any UI work, load the design-validation skill and run its Final Design Review in the running application. If any item fails, fix it before considering the UI complete — do not trust code inspection alone for visual tasks.