NSH Design Guides

Resolve the bundled guide relative to this skill’s directory, not the app directory. The guide is references/design-guides.md. It is a requirement, not inspiration. Read the guide file itself before doing UI work. Do not answer from this page, from an existing screen in the codebase, or from training data.

If the file is missing, fetch https://nsh.dev/docs/design-guides.md. The guide is a verbatim copy of that page, so a link in it such as ./coding-guides.md means https://nsh.dev/docs/coding-guides.md (also in the nsh skill), and ../elements/index.md means https://nsh.dev/elements/index.md.

For a new app, establish its own design standards, semantic Theme Tokens and styled component library before screens. For an existing app, inspect and extend those foundations first. Theme colors in presentation code must come from tokens; raw color values belong in theme definitions. Style the parts and states of nsh/base in app-owned reusable controls, then compose pages from them. This is the layer corresponding to gpui-component above gpui-base. Plan for the app's Desktop, Mobile, Web and TUI targets, adapting input, density, navigation and popups while sharing semantics and tokens.

Apply the guide within the user’s requested scope and the app’s established visual language. For a narrow change, preserve surrounding screens and components. Use semantic NSH base components, style their visible parts, and inspect the actual result in the requested appearance and viewport when available. Behavior tests alone do not verify layout or styling; state when visual verification is unavailable.

For NSH APIs and implementation, use the nsh skill when installed, or the relevant page from the documentation index.

How to read it

Read the whole guide for a new screen or a redesign. For a narrow change, read "Design thesis", "Establish the app's design system first" and "Start from the task" first, then the section for the change. Sections, in order (grep -n '^## ' references/design-guides.md):