Skip to content

DESIGN.md

Latest commit

 

History

History
433 lines (348 loc) · 17.3 KB

DESIGN.md

File metadata and controls

433 lines (348 loc) · 17.3 KB
Raw
name Kolibri
colors
surface surface-dim surface-bright surface-container-lowest surface-container-low surface-container surface-container-high surface-container-highest on-surface on-surface-variant inverse-surface inverse-on-surface outline outline-variant surface-tint primary on-primary primary-container on-primary-container inverse-primary secondary on-secondary secondary-container on-secondary-container tertiary on-tertiary tertiary-container on-tertiary-container error on-error error-container on-error-container primary-fixed primary-fixed-dim on-primary-fixed on-primary-fixed-variant secondary-fixed secondary-fixed-dim on-secondary-fixed on-secondary-fixed-variant tertiary-fixed tertiary-fixed-dim on-tertiary-fixed on-tertiary-fixed-variant background on-background surface-variant
#121414
#121414
#383939
#0d0f0f
#1a1c1c
#1e2020
#282a2a
#333535
#e2e2e2
#b9cbbd
#e2e2e2
#2f3131
#849588
#3a4a3f
#00e290
#f5fff5
#003920
#00ffa3
#007146
#006d43
#b9f1ff
#00363f
#00e0ff
#005f6d
#fffbff
#3b2f00
#ffdd67
#766000
#ffb4ab
#690005
#93000a
#ffdad6
#52ffac
#00e290
#002111
#005231
#a5eeff
#00daf8
#001f25
#004e5a
#ffe17b
#e4c451
#231b00
#564500
#121414
#e2e2e2
#333535
semantic-colors
accent glass border text donate-pink
safe warning danger
{colors.primary-fixed-dim}
{colors.tertiary-fixed-dim}
{colors.error}
surface surface-high surface-hover
rgba(30, 32, 32, 0.6)
rgba(40, 42, 42, 0.85)
rgba(40, 42, 42, 0.7)
subtle divider
rgba(255, 255, 255, 0.08)
rgba(255, 255, 255, 0.05)
muted
{colors.on-surface-variant}
#e84393
breakpoints
sm md lg xl
640px
768px
1024px
1280px
typography
display-lg headline-lg headline-lg-mobile headline-md headline-sm body-lg body-md body-sm label-md label-sm
fontFamily fontSize fontWeight lineHeight letterSpacing fontVariantNumeric
JetBrains Mono
40px
700
48px
-0.02em
tabular-nums
fontFamily fontSize fontWeight lineHeight letterSpacing fontVariantNumeric
JetBrains Mono
32px
600
40px
-0.01em
tabular-nums
fontFamily fontSize fontWeight lineHeight fontVariantNumeric
JetBrains Mono
28px
600
36px
tabular-nums
fontFamily fontSize fontWeight lineHeight fontVariantNumeric
JetBrains Mono
24px
600
32px
tabular-nums
fontFamily fontSize fontWeight lineHeight fontVariantNumeric
JetBrains Mono
20px
600
28px
tabular-nums
fontFamily fontSize fontWeight lineHeight fontVariantNumeric
JetBrains Mono
18px
400
28px
tabular-nums
fontFamily fontSize fontWeight lineHeight fontVariantNumeric
JetBrains Mono
16px
400
24px
tabular-nums
fontFamily fontSize fontWeight lineHeight fontVariantNumeric
JetBrains Mono
14px
400
20px
tabular-nums
fontFamily fontSize fontWeight lineHeight letterSpacing fontVariantNumeric
JetBrains Mono
12px
600
16px
0.05em
tabular-nums
fontFamily fontSize fontWeight lineHeight fontVariantNumeric
JetBrains Mono
10px
500
14px
tabular-nums
rounded
sm DEFAULT md lg xl full
0.25rem
0.5rem
0.75rem
1rem
1.5rem
9999px
spacing
base xs sm md lg xl margin-mobile margin-desktop gutter
8px
4px
12px
16px
24px
32px
16px
40px
16px
zIndex
nav dialog-backdrop dialog popup
50
999
1000
1100
durations
fast normal slow
150ms
200ms
300ms
easings
default
ease
animations
skeleton-pulse spin
skeleton-pulse 1.5s ease-in-out infinite
spin 1s linear infinite

Brand & Style

The design system is engineered to project a sense of institutional-grade security fused with the velocity of modern decentralized finance. It caters to a tech-savvy audience that values precision and transparency within the Tezos ecosystem.

The visual direction combines High-Tech Minimalism with Glassmorphism. This approach utilizes deep obsidian surfaces and vibrant phosphorescent accents to create a high-contrast, data-centric environment. The aesthetic is "technical-premium"—avoiding unnecessary ornamentation in favor of functional clarity and sophisticated depth. Every interaction should feel instantaneous and reliable, reinforcing the brand's position as a fast, secure gateway to liquidity.

Typeface: JetBrains Mono is used for all text. Its monospaced glyphs are critical for DeFi: numbers stay aligned when balances update, preventing layout shifts and improving scannability of financial data.

Colors

The palette is anchored in a Dark Mode foundation to reduce eye strain during prolonged financial monitoring and to emphasize the "high-tech" nature of the product.

Color roles follow the Material 3 model:

  • Primary (#f5fff5): Text and icons placed on top of the primary container. Not the button fill color.
  • Primary Container (#00ffa3): The actual neon emerald used for primary buttons, success states, and growth indicators. It should appear to "glow" against the dark background.
  • On Primary (#003920): Text color on primary containers (used for solid button labels).
  • Secondary (#b9f1ff) / Secondary Container (#00e0ff): Used for secondary data points, info links, or subtle UI accents to provide a cool-toned contrast to the green.
  • Tertiary (#fffbff) / Tertiary Container (#ffdd67): Reserved for warning or attention states, such as elevated liquidation risk.
  • Error (#ffb4ab) / Error Container (#93000a): Critical warnings and error states.
  • Surface (#121414): The near-black background. All other surfaces are layered on top of it.
  • On Surface (#e2e2e2): Primary text color.
  • On Surface Variant (#b9cbbd): Secondary text, labels, metadata.
  • Surface Tint (#00e290): Focus rings, active tab underlines, links.

Semantic Colors

These aliases map the Material roles to domain meaning:

  • accent.safe = primary-fixed-dim
  • accent.warning = tertiary-fixed-dim
  • accent.danger = error
  • glass.surface = rgba(30, 32, 32, 0.6)
  • glass.surface-high = rgba(40, 42, 42, 0.85)
  • border.subtle = rgba(255, 255, 255, 0.08)
  • border.divider = rgba(255, 255, 255, 0.05)
  • text.muted = on-surface-variant
  • donate-pink = #e84393

Typography

The design system uses JetBrains Mono for all typographic needs. Its monospaced structure is essential for DeFi dashboards where numerical alignment directly impacts readability and trust.

  • Scale: Headlines use tight letter-spacing and semi-bold weights to appear "engineered."
  • Hierarchy: Use label-md for metadata and section headers to create a rhythmic distinction between data labels and numerical values.
  • Numerics: Every numeric style (body-*, label-*) uses font-variant-numeric: tabular-nums. This prevents layout shifting when balances, prices, or percentages update in real-time.
  • Monospace: Code snippets, addresses, hashes, and transaction IDs should use the mono font family token.

Layout & Spacing

This design system follows a strict 8px grid system to ensure mathematical harmony across all components.

  • Mobile First: The layout is primarily fluid within a 16px side margin (margin-mobile). On desktop the margin is 40px (margin-desktop).
  • Grid: Use a 4-column grid for mobile (< md) and a 12-column grid for tablet/desktop (>= md).
  • Rhythm: Vertical spacing should be generous to allow the glassmorphism effects to "breathe." Use lg (24px) for section spacing and md (16px) for internal card padding.
  • Breakpoints:
    • sm: 640px
    • md: 768px
    • lg: 1024px
    • xl: 1280px

Elevation & Depth

Depth is achieved through a combination of Glassmorphism and Subtle Outlines rather than heavy shadows.

  • Layer 0 (Background): surface (#121414).
  • Layer 1 (Cards): glass.surface (rgba(30, 32, 32, 0.6)) with a 16px–32px backdrop-blur. Each card is finished with a 1px solid border.subtle (8% white opacity) to define its edges against the dark background.
  • Layer 2 (Modals/Popovers): glass.surface-high (rgba(40, 42, 42, 0.85)) with a more pronounced white inner-stroke to simulate closer physical proximity to the user.
  • Layer 3 (Nav/Floating): Fixed navbar also uses glass.surface with backdrop-blur.
  • Shadows: Only used sparingly on floating action buttons (FABs) using a colored glow (#00FFA3 at 20% opacity) rather than a black shadow. Dialogs use dialog-glow.
  • Performance Fallback: On low-end devices or when prefers-reduced-transparency is active, replace backdrop-filter: blur(...) with an opaque surface-container-high background to avoid GPU strain and maintain readability.

Shapes

The shape language is "Soft-Tech." While the brand is professional, purely sharp corners are avoided to maintain a user-friendly and approachable feel.

  • Base Radius: 8px (rounded-DEFAULT) for standard components like input fields and small buttons.
  • Medium Radius: 12px (rounded-md) for segmented controls and radio cards.
  • Large Radius: 16px (rounded-lg) for main container cards and dialogs.
  • Extra Radius: 24px (rounded-xl) for featured dashboard modules.
  • Pill Radius: 9999px (rounded-full) for buttons, chips, and wallet balance badges.

Motion & Animation

All transitions should feel instantaneous yet polished. DeFi interfaces update in real time, so motion must be calm and not distracting.

  • Fast (150ms): Hover states, focus rings, button presses, chip toggles.
  • Normal (200ms): Dialog open/close, tab transitions, radio card selection.
  • Slow (300ms): Progress bar fills, large layout shifts.
  • Easing: Default ease. Avoid bouncy or playful easings.
  • Skeleton: skeleton-pulse animation (1.5s ease-in-out infinite) for loading placeholders.
  • Spinner: spin animation (1s linear infinite) for loading buttons.
  • Disabled: Prefer opacity: 0.5 + cursor: not-allowed over grayscale for disabled states.

Iconography

  • Library: lucide-react is the single source of truth for icons. Avoid mixing icon sets.
  • Sizes:
    • 12px–14px: inline buttons, chips, copy button.
    • 16px–20px: default UI icons in cards and dialogs.
    • 24px–28px: navbar actions, feature illustrations.
  • Color: Default to on-surface-variant. Use primary-fixed-dim for accent/CTA icons, error for warnings, tertiary-fixed-dim for cautionary states.
  • Stroke: Default Lucide stroke (1.5–2). Do not adjust stroke width per icon unless necessary for optical balance.
  • Loading: Use Loader2 with the spin animation token. Never use a static spinner icon without animation.

Accessibility

  • Contrast: Aim for WCAG AA 4.5:1 for all text. on-surface/on-surface-variant on surface layers already meet this. Be cautious when placing text on glass surfaces over complex backgrounds—use a solid surface-container-* fallback if needed.
  • Focus: Every interactive element must have a visible focus-visible ring using surface-tint (2px outline).
  • Motion: Respect prefers-reduced-motion where possible; reduce or disable backdrop-blur for prefers-reduced-transparency.
  • Screen Readers: Use Base UI primitives (Dialog, Tabs, Combobox, Tooltip) for correct ARIA roles. Never build custom select/dropdown/ modal from scratch.

Component Spacing Map

Component Padding Gap Notes
Button (sm) px: md, py: sm — Pill shape, 28px height
Button (md) px: lg, py: sm — 36px height
Button (lg) px: xl, py: md — 44px height
Icon Button 0 — Fixed width/height by size
Card padding: md gap: xs rounded-lg
Dialog padding: lg gap: md rounded-lg
Input 8px 12px — rounded-md
Input Group — — Input + suffix/chip, focus ring on group root
Radio Card padding: sm gap: sm rounded-md
Chip 2px 8px — rounded-full
Data Row paddingY: sm optional — divider variant adds border-bottom
Segmented Tabs padding: xs gap: xs rounded-md container, rounded-sm items
Skeleton Inline width: w prop — Uses shape="inline"

Components

Buttons

Buttons use a variant × tone matrix. This avoids a combinatorial explosion of one-off variants.

  • Variants: solid, outline, ghost, icon.
  • Tones: primary, warning, danger.
  • Sizes: sm, md, lg.
  • States:
    • Default: defined by variant + tone.
    • Hover: solid uses opacity; outline/ghost use a tinted transparent overlay (/5–/15).
    • Active: transform: scale(0.96) for all variants (solid, outline, ghost, chips, currency toggles).
    • Disabled: opacity: 0.5, cursor: not-allowed.
    • Loading: aria-busy="true", spinner icon, preserves disabled state.

Cards

  • Base: glass.surface + border.subtle + rounded-lg.
  • accent: none / safe / warning / danger — adds a 4px left border in the corresponding accent color.
  • interactive: hover background shifts to glass.surface-hover.
  • Avoid putting complex gradients inside borders; rely on the glass surface and subtle outline.

Inputs

  • Background: surface-container.
  • Border: 1px solid outline-variant.
  • Border radius: rounded-md.
  • Focus: border color changes to surface-tint with a 1px outline glow (box-shadow: 0 0 0 1px surface-tint).
  • Error: border color error, text color error for the description.
  • Disabled: opacity: 0.5.

Dialogs

  • Backdrop: surface/60 + backdrop-blur(8px), z-index dialog-backdrop.
  • Popup: glass.surface-high + border.subtle + rounded-lg, z-index dialog.
  • Sizes: md (default, headline-sm title) and sm (body-lg title).
  • Close button: icon-only Button with X icon, positioned top-right.
  • Animation: opacity + scale transitions (200ms).

Tabs

  • underline: bottom border tab list, active tab underlined with surface-tint.
  • segmented: pill container (surface-container-lowest), selected item uses primary-container/15 background and primary-fixed-dim color.
  • Use data-selected for styling, not render-prop className merging.

Progress

  • Track: surface-container-highest, rounded-full, height 4px.
  • Indicator colors by level: safe (accent.safe), warning (accent.warning), danger (accent.danger).
  • Indicator glow uses the same color at 60% opacity (token(colors.x, 0.6)).
  • Width is managed by Base UI; do not set it manually.

Radio Cards

  • Base: surface-container + outline-variant border + rounded-md.
  • Hover: surface-container-high.
  • Checked: primary-container border + primary-container/6 background via &[data-checked].

Chips / Badges

Used for "LTV", "APY", "Status" and currency toggles.

  • Colors: primary, warning, error.
  • Style: low-opacity background (/12) with the saturated text color.
  • Shape: pill (rounded-full).

Data Rows

Use the dataRow recipe:

  • Flex row, justify-content: space-between, align-items: center.
  • textStyle: body-sm.
  • Optional divider variant adds a 1px border.divider bottom and padding-bottom: sm / margin-bottom: sm.
  • Numerical values are right-aligned, labels left-aligned.

Skeleton

Use the <Skeleton /> component with shape and optional w (width) prop.

  • inline: for text/number placeholders.
  • text / heading / circle / block: for generic block placeholders.
  • Animation: skeleton-pulse token.

Copy Button

  • Icon-only Button (variant="icon", size="sm").
  • Icons: Copy default, Check after success (with primary-fixed-dim color).
  • Tooltip: "Copy" on hover, "Copied" after click. Wrapped in Tooltip.Positioner for correct placement.

Autocomplete

Built on Base UI Combobox for full keyboard navigation (arrows, enter, escape) and accessibility.

  • Input uses the existing input recipe.
  • Popup uses the popup recipe.
  • Items render their label directly, not inside ItemIndicator.
  • Item hover uses primary-container/6, selected item uses primary-container/10.

Responsive Notes

  • Mobile: single-column card grids, full-width dialogs, compact navbar icons.
  • Tablet/Desktop: multi-column grids (md: 2 cols, lg: 3 cols for ovens), wider margins.
  • Dialogs should remain centered and bounded by max-width: 480px on all viewports.