# Decent Design System (Decent DS) Decent DS is the visual and interaction language shared by every screen in Decent Billing ERP. It is inspired by (but does not copy) Linear, Notion, Stripe Dashboard, Laravel Nova, Filament, TailAdmin, and Tabler. The goal is a fast, clean, spacious, professional interface that feels equally at home on a phone at a kirana counter and on a large monitor in a wholesaler's back office. ## 1. Foundations ### 1.1 Color tokens All color values live in `resources/css/tokens.scss` as SCSS maps and are projected onto CSS custom properties by `_theme-light.scss` and `_theme-dark.scss`. **Components must reference `--dc-*` variables only.** No literal hex values are allowed outside these two theme files. | Variable | Usage | |----------------------------|------------------------------------------------| | `--dc-bg-canvas` | App-level background | | `--dc-bg-surface` | Cards, modals, dropdowns | | `--dc-bg-elevated` | Popovers, tooltips | | `--dc-bg-muted` | Subtle sections and separators | | `--dc-border-subtle` | Standard 1px borders | | `--dc-border-strong` | Emphasised borders (focus, active) | | `--dc-text-primary` | Body copy | | `--dc-text-secondary` | Metadata, labels | | `--dc-text-muted` | Placeholders, disabled | | `--dc-brand-primary` | Primary CTA, brand marks | | `--dc-brand-primary-hover` | Hover state for primary CTA | | `--dc-brand-secondary` | Secondary/accent CTA | | `--dc-brand-accent` | Highlights, statistical accents | | `--dc-success` | Positive semantics (paid, in-stock, healthy) | | `--dc-info` | Neutral emphasis | | `--dc-warning` | Caution (low stock, near due date) | | `--dc-danger` | Errors, destructive actions | Semantic tones are always used by name (`success`, `info`, `warning`, `danger`), never by referencing the underlying brand color. ### 1.2 Typography - Body: `Inter`, with fallbacks to Indian language stacks (`Noto Sans Devanagari`, `Noto Sans Gujarati`, `Noto Sans Tamil`, `Noto Sans Telugu`, `Noto Sans Kannada`, `Noto Sans Malayalam`, `Noto Sans Bengali`, `Noto Sans Gurmukhi`, `Noto Nastaliq Urdu`) followed by system fonts. - Monospace: `JetBrains Mono` for tabular numbers, code, invoice numbers. - Type scale: 12 / 13 / 14 / 16 / 18 / 20 / 24 / 30 / 36 / 48 (px). Line heights follow a 1.5 rhythm for body and 1.2 for headings. ### 1.3 Spacing and radii - Spacing scale: `4, 8, 12, 16, 20, 24, 32, 40, 48, 64` (px). - Radii: `sm=6px`, `md=10px`, `lg=14px`, `xl=20px`, `pill=999px`. ### 1.4 Shadows and elevation - `sm` - Border-mimicking, for input focus. - `md` - Cards, dropdown menus. - `lg` - Modals, popovers. - `xl` - Command palette (added in S0.4). ### 1.5 Motion - Duration tokens: `120ms` (micro), `200ms` (default), `280ms` (transitions). - Easing: `cubic-bezier(.2, .8, .2, 1)` for enter, `cubic-bezier(.4, 0, 1, 1)` for exit. - All motion respects `prefers-reduced-motion`. ## 2. Layout ### 2.1 Shell The admin shell (`.dc-shell`) is a CSS Grid with three regions: ``` [ sidebar ][ topbar ] [ sidebar ][ content ] ``` - Sidebar width: 268px expanded, 72px collapsed. - Topbar height: 60px. - Content is a max-width `1440px` column with 24px padding on desktop, 16px on tablet, and 12px on mobile. ### 2.2 Responsive rules - **Mobile first.** All components default to a stacked, single-column layout and progressively enhance. - Sidebar becomes an off-canvas drawer under `992px` with a translucent backdrop. - Tables switch to card-list rows under `768px`; each row is tappable and shows the key-value pairs stacked with clear labels. - All interactive targets are at least `44x44px` on touch. ### 2.3 Density modes - `density-comfortable` (default) - 12px vertical rhythm in inputs, 40px primary button height. - `density-compact` - 8px vertical rhythm, 32px button height. Used by users who process high volumes of invoices at a POS counter. ## 3. Components The `resources/views/components/*` folder is the canonical registry. Every component: - Accepts explicit `@props` with sensible defaults. - Never contains business logic. - Renders semantic HTML (`button`, `nav`, `header`, `main`, `aside`). - Announces state to assistive tech (`aria-*`, `role`). Current components (S0.1): - `icon` - Renders a Lucide-family SVG from a fixed dictionary. - `card` - Surface + header + body + footer slots. - `stat` - Number + label + delta indicator. - `button` - Variants: primary, secondary, ghost, danger; sizes: sm, md, lg; optional `icon`, `block`. - `badge` - Semantic tones; count, dot, and label variants. - `alert` - Semantic tones with dismissible option. - `input`, `select`, `textarea` - Bootstrap 5.3 form controls skinned by Decent DS. - `empty-state` - Illustration slot + title + description + CTA slot. - `nav.sidebar` - Sidebar navigation. - `nav.theme-toggle` - Three-way theme control (light/system/dark). - `nav.breadcrumbs` - Semantic breadcrumb trail. ## 4. Theming - `theme_class()` on the server maps the user's preference to a class on `` (`theme-light`, `theme-dark`, `theme-system`). - The `theme-system` class opts into `prefers-color-scheme`, so users who toggle the OS-level dark mode see the app follow along. - The client `ThemeController` (`resources/js/modules/theme.js`) listens to `matchMedia('(prefers-color-scheme: dark)')` and updates the class in place; it also persists the choice through `POST /preferences`. ## 5. Accessibility baseline - Every focusable element shows a `2px` ring in `--dc-brand-primary`. - Skip link ("Skip to main content") is the first tab stop on every page. - Color contrast for text vs surface passes WCAG 2.1 AA in both themes. - No color-only signalling: semantic tones are paired with an icon or a text label. - Motion respects `prefers-reduced-motion: reduce` and turns off shimmer animations on skeletons. ## 6. Forbidden patterns - No hard-coded colors in modules. Always use `--dc-*`. - No inline `