docs: add DESIGN.md for sistent design system#1458
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the DESIGN.md file, which outlines the 'Sistent' design system, including its visual identity, color palettes, typography, and component specifications for both light and dark modes. The review feedback highlights several opportunities for improvement: consolidating redundant corner radius tokens, replacing hardcoded color and gradient values with defined tokens for better maintainability, and addressing inconsistencies between the stated 8px grid principle and actual padding values. Additionally, a discrepancy was noted between the documentation's description of card effects and the current token definitions.
| xl: 15px | ||
| xxl: 16px |
There was a problem hiding this comment.
Having both 15px and 16px as distinct corner radius tokens is likely redundant. In a consistent design system, these would typically be consolidated into a single value (e.g., 16px) to avoid micro-variations that are difficult to distinguish visually.
| rounded: "{rounded.xs}" | ||
| size: 20px | ||
| modal-header-light: | ||
| backgroundColor: "linear-gradient(90deg, #477E96 0%, #455A64 100%)" |
There was a problem hiding this comment.
This hardcoded gradient string matches the gradients.tint-light token defined on line 143. Referencing the token directly improves maintainability.
| backgroundColor: "linear-gradient(90deg, #477E96 0%, #455A64 100%)" | |
| backgroundColor: "{gradients.tint-light}" |
| height: 52px | ||
| padding: 11px 16px | ||
| modal-header-dark: | ||
| backgroundColor: "linear-gradient(90deg, #28353A 0%, #3D4F57 100%)" |
There was a problem hiding this comment.
This hardcoded gradient string matches the gradients.tint-dark token defined on line 144. Referencing the token directly improves maintainability.
| backgroundColor: "linear-gradient(90deg, #28353A 0%, #3D4F57 100%)" | |
| backgroundColor: "{gradients.tint-dark}" |
| height: 52px | ||
| padding: 11px 16px | ||
| panel-floating-light: | ||
| backgroundColor: "rgba(234, 237, 238, 0.5)" |
There was a problem hiding this comment.
This hardcoded color value matches the effects.panel-blur-light token defined on line 149. Referencing the token directly improves maintainability.
| backgroundColor: "rgba(234, 237, 238, 0.5)" | |
| backgroundColor: "{effects.panel-blur-light}" |
| rounded: "{rounded.lg}" | ||
| padding: "{spacing.xl}" | ||
| panel-floating-dark: | ||
| backgroundColor: "rgba(0, 13, 18, 0.5)" |
There was a problem hiding this comment.
This hardcoded color value matches the effects.panel-blur-dark token defined on line 150. Referencing the token directly improves maintainability.
| backgroundColor: "rgba(0, 13, 18, 0.5)" | |
| backgroundColor: "{effects.panel-blur-dark}" |
| Spacing follows a clear **8px grid**. The most common working values are `16px`, `20px`, and `24px`, with `12px` used for more compact interactive padding and `32px` reserved for larger layout separation. | ||
|
|
||
| The system generally prefers compact, information-dense arrangement over expansive marketing whitespace. That said, it avoids feeling cramped by keeping horizontal padding predictable and by separating structural chrome from content with tonal layers instead of large gutters. | ||
|
|
||
| - **Buttons and tabs** commonly use `16px` horizontal padding. | ||
| - **Modal headers** and action bars land on `11px 16px` and `20px 16px` style rhythms. | ||
| - **Panels and cards** stay tidy; they read as tools, not canvas art. |
There was a problem hiding this comment.
There is an inconsistency between the stated design principle and the documented values. While line 329 claims a "clear 8px grid", the prose on line 334 mentions 11px and 20px rhythms, and several component tokens (e.g., lines 177, 235, 253) use off-grid values like 6px, 11px, and 14px. Consider aligning these to the 8px grid or clarifying the exceptions.
|
|
||
| Depth in Sistent is subtle. Most surfaces separate through **tone**, **border**, and **surface step**, not through large shadows. This keeps tables, cards, and forms feeling crisp and controlled. | ||
|
|
||
| - **Standard cards** use a very faint radial wash rather than dramatic dropshadow. |
There was a problem hiding this comment.
The prose states that standard cards use a "very faint radial wash", but the card-standard-light and card-standard-dark component tokens (lines 208-217) do not include the card-wash effect defined on line 148. This creates a discrepancy between the documentation and the token definitions.
There was a problem hiding this comment.
Pull request overview
Adds a root-level design reference document for Sistent, combining a YAML token set (light/dark foundations + representative component tokens) with prose describing usage guidance and visual principles.
Changes:
- Introduces
DESIGN.mdcontaining a YAML token catalog for colors, typography, spacing, radii, motion, gradients, shadows, elevation, effects, and sample component recipes. - Adds narrative sections describing palette intent, typographic hierarchy, layout/spacing rules, elevation usage, shapes, and component guidance (buttons, tabs, inputs, cards/panels).
- Includes a “Do’s and Don’ts” checklist for consistent application of the system.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --- | ||
| version: alpha | ||
| name: Sistent | ||
| description: Open-source dashboard and component-system visual identity with a neutral application shell, teal brand actions, saffron CTAs, and a first-class dark mode. |
There was a problem hiding this comment.
The design tokens are currently placed in YAML front matter. On GitHub this renders as plain text (no YAML syntax highlighting), and in some Markdown pipelines front matter is treated as metadata rather than content, which can make the token section harder to consume as documentation. If this file is meant to be read directly in the repo, consider moving the token YAML into a fenced ```yaml block (or duplicating it there) and keeping front matter for page metadata only.
| description: Open-source dashboard and component-system visual identity with a neutral application shell, teal brand actions, saffron CTAs, and a first-class dark mode. | |
| description: Open-source dashboard and component-system visual identity with a neutral application shell, teal brand actions, saffron CTAs, and a first-class dark mode. | |
| --- | |
| ## Design tokens | |
| ```yaml |
| text-h1-bold: | ||
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | ||
| fontSize: 3.25rem | ||
| fontWeight: "700" | ||
| lineHeight: 4rem | ||
| letterSpacing: -0.02em | ||
| text-h2-medium: | ||
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | ||
| fontSize: 2rem | ||
| fontWeight: "500" | ||
| lineHeight: 2.5rem | ||
| text-h3-medium: | ||
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | ||
| fontSize: 1.5rem | ||
| fontWeight: "500" | ||
| lineHeight: 2.25rem | ||
| text-b1-regular: | ||
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | ||
| fontSize: 1rem | ||
| fontWeight: "400" | ||
| lineHeight: 1.75rem | ||
| text-b2-semibold: | ||
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | ||
| fontSize: 1rem | ||
| fontWeight: "600" | ||
| lineHeight: 1.75rem | ||
| text-b3-regular: | ||
| fontFamily: "Open Sans, sans-serif" | ||
| fontSize: 0.875rem | ||
| fontWeight: "400" | ||
| lineHeight: 1.5rem | ||
| text-l1-bold: | ||
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | ||
| fontSize: 0.75rem | ||
| fontWeight: "700" | ||
| lineHeight: 1rem | ||
| letterSpacing: 0.02em | ||
| text-l2-regular: | ||
| fontFamily: "Open Sans, sans-serif" | ||
| fontSize: 0.75rem | ||
| fontWeight: "400" | ||
| lineHeight: 1.5rem | ||
| text-c1-regular: | ||
| fontFamily: "Consolas, monospace" | ||
| fontSize: 0.75rem | ||
| fontWeight: "400" | ||
| lineHeight: 1.5rem | ||
| text-c2-regular: |
There was a problem hiding this comment.
Token naming here (e.g., typography.text-h1-bold, text-b2-semibold) uses kebab-case, but the codebase’s theme typography variants are camelCase (e.g., textH1Bold, textB2SemiBold in src/theme/typography.ts). If these tokens are intended to map to the implemented theme, it would help to either align the names with the actual variant keys or add an explicit mapping section to prevent consumers from using non-existent token names.
| text-h1-bold: | |
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | |
| fontSize: 3.25rem | |
| fontWeight: "700" | |
| lineHeight: 4rem | |
| letterSpacing: -0.02em | |
| text-h2-medium: | |
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | |
| fontSize: 2rem | |
| fontWeight: "500" | |
| lineHeight: 2.5rem | |
| text-h3-medium: | |
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | |
| fontSize: 1.5rem | |
| fontWeight: "500" | |
| lineHeight: 2.25rem | |
| text-b1-regular: | |
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | |
| fontSize: 1rem | |
| fontWeight: "400" | |
| lineHeight: 1.75rem | |
| text-b2-semibold: | |
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | |
| fontSize: 1rem | |
| fontWeight: "600" | |
| lineHeight: 1.75rem | |
| text-b3-regular: | |
| fontFamily: "Open Sans, sans-serif" | |
| fontSize: 0.875rem | |
| fontWeight: "400" | |
| lineHeight: 1.5rem | |
| text-l1-bold: | |
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | |
| fontSize: 0.75rem | |
| fontWeight: "700" | |
| lineHeight: 1rem | |
| letterSpacing: 0.02em | |
| text-l2-regular: | |
| fontFamily: "Open Sans, sans-serif" | |
| fontSize: 0.75rem | |
| fontWeight: "400" | |
| lineHeight: 1.5rem | |
| text-c1-regular: | |
| fontFamily: "Consolas, monospace" | |
| fontSize: 0.75rem | |
| fontWeight: "400" | |
| lineHeight: 1.5rem | |
| text-c2-regular: | |
| textH1Bold: | |
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | |
| fontSize: 3.25rem | |
| fontWeight: "700" | |
| lineHeight: 4rem | |
| letterSpacing: -0.02em | |
| textH2Medium: | |
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | |
| fontSize: 2rem | |
| fontWeight: "500" | |
| lineHeight: 2.5rem | |
| textH3Medium: | |
| fontFamily: "Qanelas Soft Regular, Roboto, Helvetica, Arial, sans-serif" | |
| fontSize: 1.5rem | |
| fontWeight: "500" | |
| lineHeight: 2.25rem | |
| textB1Regular: | |
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | |
| fontSize: 1rem | |
| fontWeight: "400" | |
| lineHeight: 1.75rem | |
| textB2SemiBold: | |
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | |
| fontSize: 1rem | |
| fontWeight: "600" | |
| lineHeight: 1.75rem | |
| textB3Regular: | |
| fontFamily: "Open Sans, sans-serif" | |
| fontSize: 0.875rem | |
| fontWeight: "400" | |
| lineHeight: 1.5rem | |
| textL1Bold: | |
| fontFamily: "Qanelas Soft Regular, Open Sans, sans-serif" | |
| fontSize: 0.75rem | |
| fontWeight: "700" | |
| lineHeight: 1rem | |
| letterSpacing: 0.02em | |
| textL2Regular: | |
| fontFamily: "Open Sans, sans-serif" | |
| fontSize: 0.75rem | |
| fontWeight: "400" | |
| lineHeight: 1.5rem | |
| textC1Regular: | |
| fontFamily: "Consolas, monospace" | |
| fontSize: 0.75rem | |
| fontWeight: "400" | |
| lineHeight: 1.5rem | |
| textC2Regular: |
|
@copilot @gemini-review-assist this design.md file must adhere to the DESIGN.md specification - https://github.com/google-labs-code/design.md |
Updated in c76a423. The file now keeps YAML front matter as the normative token source required by the DESIGN.md spec, and the typography token keys/component references are aligned with Sistent’s implemented theme variant names. Screenshot: N/A — docs-only change. |
Summary
DESIGN.mdat the project rootNotes
design.mdlint reports no errors; remaining warnings reflect existing low-contrast teal/white and ribbon treatments already present in the shipped UI