@scania/tegel-lite 0.0.1 → 0.0.2-rules-beta.0

package/.cursor/rules/tegel-lite/04-components-navigation.mdc

@@ -0,0 +1,357 @@
+---
+description: 04-components-navigation
+alwaysApply: true
+---
+# Navigation & Utility Components
+
+## Breadcrumbs
+
+**Classes**: `tl-breadcrumbs`
+
+```html
+<nav class="tl-breadcrumbs" aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/products">Products</a></li>
+    <li><a href="/products/trucks" aria-current="page">Trucks</a></li>
+  </ol>
+</nav>
+```
+
+---
+
+## Chip
+
+**Classes**: `tl-chip`
+**Sizes**: `tl-chip--sm` (24px), `tl-chip--lg` (32px)
+**States**: `tl-chip--selected`
+**Modifiers**: `tl-chip--prefix`, `tl-chip--suffix`
+
+```html
+<button class="tl-chip tl-chip--lg">Default</button>
+<button class="tl-chip tl-chip--lg tl-chip--selected">Selected</button>
+<button class="tl-chip tl-chip--sm" disabled>Disabled</button>
+```
+
+---
+
+## Tabs
+
+### Inline Tabs
+
+```html
+<div class="tl-inline-tabs" role="tablist">
+  <button
+    class="tl-inline-tabs__tab tl-inline-tabs__tab--selected"
+    role="tab"
+    aria-selected="true"
+  >
+    Tab 1
+  </button>
+  <button class="tl-inline-tabs__tab" role="tab" aria-selected="false">
+    Tab 2
+  </button>
+  <button
+    class="tl-inline-tabs__tab tl-inline-tabs__tab--disabled"
+    role="tab"
+    aria-disabled="true"
+  >
+    Disabled
+  </button>
+</div>
+```
+
+### Folder Tabs
+
+```html
+<div class="tl-folder-tabs" role="tablist">
+  <button
+    class="tl-folder-tabs__tab tl-folder-tabs__tab--selected"
+    role="tab"
+    aria-selected="true"
+  >
+    Active
+  </button>
+  <button class="tl-folder-tabs__tab" role="tab" aria-selected="false">
+    Another
+  </button>
+</div>
+```
+
+### Navigation Tabs
+
+```html
+<nav class="tl-navigation-tabs" role="tablist">
+  <a
+    class="tl-navigation-tabs__tab tl-navigation-tabs__tab--selected"
+    href="/overview"
+    role="tab"
+    aria-selected="true"
+    >Overview</a
+  >
+  <a class="tl-navigation-tabs__tab" href="/details" role="tab">Details</a>
+</nav>
+```
+
+---
+
+## Link
+
+**Classes**: `tl-link`
+**Modifiers**: `tl-link--underline`, `tl-link--standalone`, `tl-link--disabled`
+
+```html
+<a href="/page" class="tl-link tl-link--underline">
+  Learn more
+  <span class="tl-link__icon"
+    ><span class="tl-icon tl-icon--arrow_right"></span
+  ></span>
+</a>
+
+<!-- Standalone link (inherits detail-02 typography) -->
+<a href="/page" class="tl-link tl-link--standalone tl-link--underline"
+  >Standalone Link</a
+>
+
+<!-- Disabled link -->
+<span class="tl-link tl-link--disabled">Disabled link</span>
+```
+
+---
+
+## Divider
+
+**Classes**: `tl-divider`
+**Variants**: `tl-divider--horizontal`, `tl-divider--vertical`, `tl-divider--expressive`, `tl-divider--discrete`
+
+```html
+<div class="tl-divider tl-divider--horizontal"></div>
+<div class="tl-divider tl-divider--vertical" style="height: 40px;"></div>
+```
+
+---
+
+## Tooltip
+
+**Classes**: `tl-tooltip`
+**Modifiers**: `tl-tooltip--visible`, position variants: `tl-tooltip--top-start`, `tl-tooltip--top-end`, `tl-tooltip--bottom-start`, `tl-tooltip--bottom-end`, `tl-tooltip--left-start`, `tl-tooltip--left-end`, `tl-tooltip--right-start`, `tl-tooltip--right-end`
+
+```html
+<div class="tl-tooltip tl-tooltip--visible tl-tooltip--bottom-start">
+  Tooltip text here
+</div>
+```
+
+Max width: 204px. Positioning requires JS or CSS `position: fixed`.
+
+---
+
+## Popover Menu
+
+**Classes**: `tl-popover-menu`
+**Variants**: `tl-popover-menu--primary`, `tl-popover-menu--secondary`, `tl-popover-menu--visible`, `tl-popover-menu--fluid`
+
+```html
+<div
+  class="tl-popover-menu tl-popover-menu--visible tl-popover-menu--animation-fade"
+>
+  <div class="tl-popover-menu__item-wrapper">
+    <button class="tl-popover-menu__item">
+      <span class="tl-icon tl-icon--edit"></span>
+      Edit
+    </button>
+    <button class="tl-popover-menu__item">
+      <span class="tl-icon tl-icon--copy"></span>
+      Duplicate
+    </button>
+    <div class="tl-divider tl-divider--horizontal"></div>
+    <button class="tl-popover-menu__item--disabled">
+      <span class="tl-icon tl-icon--trash"></span>
+      Delete
+    </button>
+  </div>
+</div>
+```
+
+---
+
+## Slider
+
+**Classes**: `tl-slider`
+**Sizes**: default, `tl-slider--small`
+
+Slider requires JavaScript for thumb positioning. CSS provides the visual styling only.
+
+---
+
+## Icon
+
+**Classes**: `tl-icon tl-icon--{name}`
+**Sizes**: `tl-icon--12` through `tl-icon--96` (even numbers only)
+
+Common icons:
+
+- Navigation: `arrow_left`, `arrow_right`, `arrow_up`, `arrow_down`, `chevron_down`, `chevron_up`, `chevron_left`, `chevron_right`, `back`
+- Actions: `edit`, `trash`, `copy`, `save`, `download`, `upload`, `export`, `search`, `filters`, `settings`, `plus`, `minus`, `cross`, `tick`
+- Status: `error`, `warning`, `info`, `tick`
+- UI: `burger`, `bento`, `kebab`, `meatballs`, `eye`, `eye_inactive`, `lock`, `unlock`
+- Objects: `calendar`, `clock`, `document`, `folder`, `image`, `profile`, `home`, `notification`
+
+```html
+<span class="tl-icon tl-icon--search"></span>
+<span class="tl-icon tl-icon--search tl-icon--24"></span>
+<span class="tl-icon tl-icon--error tl-icon--16"></span>
+```
+
+Icons inherit `color` from parent via `currentcolor`.
+
+---
+
+## Header
+
+**Classes**: `tl-header`
+
+```html
+<header class="tl-header">
+  <nav class="tl-header__nav">
+    <ul class="tl-header__list">
+      <!-- Brand logo -->
+      <li class="tl-header__item">
+        <a class="tl-header__item-wrapper" href="/">
+          <span class="tl-header__brand"></span>
+        </a>
+      </li>
+
+      <!-- Title -->
+      <li class="tl-header__item">
+        <div class="tl-header__title">
+          <span class="tl-header__title-text">Application Name</span>
+        </div>
+      </li>
+
+      <!-- Nav items -->
+      <li class="tl-header__item">
+        <a class="tl-header__item-wrapper" href="/dashboard">Dashboard</a>
+      </li>
+
+      <!-- Spacer -->
+      <li class="tl-header__middle-spacer"></li>
+
+      <!-- Dropdown -->
+      <li class="tl-header__dropdown">
+        <button class="tl-header__dropdown-wrapper" aria-expanded="false">
+          <span class="tl-icon tl-icon--profile"></span>
+        </button>
+        <ul class="tl-header__dropdown-menu">
+          <li class="tl-header__dropdown-menu-item">
+            <a href="/settings">Settings</a>
+          </li>
+          <li class="tl-header__dropdown-menu-item">
+            <button>Logout</button>
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </nav>
+</header>
+```
+
+---
+
+## Footer
+
+**Classes**: `tl-footer`
+**Variants**: `tl-footer--primary`, `tl-footer--secondary`
+
+```html
+<footer class="tl-footer">
+  <!-- Top section with link groups -->
+  <div class="tl-footer__top">
+    <div class="tl-footer__group">
+      <button class="tl-footer__top-title">Resources</button>
+      <a class="tl-footer__link" href="#">Documentation</a>
+      <a class="tl-footer__link" href="#">API Reference</a>
+    </div>
+    <div class="tl-footer__group">
+      <button class="tl-footer__top-title">Support</button>
+      <a class="tl-footer__link" href="#">Contact</a>
+      <a class="tl-footer__link" href="#">FAQ</a>
+    </div>
+  </div>
+
+  <!-- Main section with brand -->
+  <div class="tl-footer__main">
+    <div class="tl-footer__main-top">
+      <div class="tl-footer__main-top--start">
+        <div class="tl-footer__group">
+          <a class="tl-footer__link" href="#">Privacy Policy</a>
+          <a class="tl-footer__link" href="#">Cookie Policy</a>
+        </div>
+      </div>
+    </div>
+    <div class="tl-footer__main-bottom">
+      <p class="tl-footer__copyright">© 2025 Scania CV AB</p>
+      <span class="tl-footer__brand">Scania</span>
+    </div>
+  </div>
+</footer>
+```
+
+---
+
+## Side Menu
+
+**Classes**: `tl-side-menu`
+**Modifiers**: `tl-side-menu--persistent`, `tl-side-menu--collapsed`
+
+```html
+<nav class="tl-side-menu tl-side-menu--persistent" aria-label="Side navigation">
+  <div class="tl-side-menu__wrapper tl-side-menu__wrapper--open">
+    <div class="tl-side-menu__overlay"></div>
+    <aside class="tl-side-menu__aside">
+      <div class="tl-side-menu__navigation">
+        <div class="tl-side-menu__list-wrapper">
+          <ul class="tl-side-menu__upper-list">
+            <li>
+              <a
+                class="tl-side-menu__item tl-side-menu__item--selected"
+                href="/dashboard"
+              >
+                <span class="tl-icon tl-icon--dashboard"></span>
+                Dashboard
+              </a>
+            </li>
+            <li>
+              <!-- Dropdown -->
+              <div class="tl-side-menu__dropdown">
+                <button class="tl-side-menu__item">
+                  <span class="tl-icon tl-icon--settings"></span>
+                  Settings
+                </button>
+                <div class="tl-side-menu__dropdown-menu">
+                  <ul class="tl-side-menu__dropdown-list">
+                    <li>
+                      <a
+                        class="tl-side-menu__dropdown-item"
+                        href="/settings/general"
+                        >General</a
+                      >
+                    </li>
+                    <li>
+                      <a
+                        class="tl-side-menu__dropdown-item"
+                        href="/settings/account"
+                        >Account</a
+                      >
+                    </li>
+                  </ul>
+                </div>
+              </div>
+            </li>
+          </ul>
+        </div>
+      </div>
+    </aside>
+  </div>
+</nav>
+```

package/.cursor/rules/tegel-lite/05-guidelines.mdc

@@ -0,0 +1,143 @@
+---
+description: 05-guidelines
+alwaysApply: true
+---
+# Guidelines
+
+## Spacing & Sizing Rules
+
+### Spacing Custom Properties (available globally)
+
+These are used by components internally and can be used for custom layouts:
+
+- `--tds-spacing-element-4` (4px)
+- `--tds-spacing-element-8` (8px)
+- `--tds-spacing-element-12` (12px)
+- `--tds-spacing-element-16` (16px)
+- `--tds-spacing-element-20` (20px)
+- `--tds-spacing-element-24` (24px)
+- `--tds-spacing-element-32` (32px)
+- `--tds-spacing-element-48` (48px)
+- `--tds-spacing-layout-64` (64px)
+
+### Rules
+
+1. Use `var(--dimension-space-small)` (16px) as the base gap between elements.
+2. Use `var(--dimension-space-medium)` (24px) for section padding.
+3. Use `var(--dimension-space-large)` (48px) for major section separators.
+4. Component height follows the sizing convention: sm=40px, md=48px, lg=56px.
+
+---
+
+## Color Usage
+
+### Semantic Color Usage
+
+| Purpose                   | Token to Use                                  |
+| ------------------------- | --------------------------------------------- |
+| Page background           | `var(--color-background-base)`                |
+| Card/section background   | `var(--color-background-layer-01)`            |
+| Nested section background | `var(--color-background-layer-02)`            |
+| Primary heading text      | `var(--color-foreground-text-strong)`         |
+| Secondary text            | `var(--color-foreground-text-defined)`        |
+| Subtle/hint text          | `var(--color-foreground-text-subtle)`         |
+| Link text                 | `var(--color-foreground-text-accent-default)` |
+| Disabled text             | `var(--color-foreground-text-disabled)`       |
+| Default border            | `var(--color-foreground-border-soft)`         |
+| Focus outline             | `var(--color-foreground-border-accent-focus)` |
+| Success state             | `var(--color-system-success-default)`         |
+| Warning state             | `var(--color-system-warning-default)`         |
+| Error/danger state        | `var(--color-system-danger-default)`          |
+| Info state                | `var(--color-system-info-default)`            |
+
+### RULE: Never hardcode colors. Always use CSS custom properties.
+
+---
+
+## Responsiveness
+
+### Breakpoints
+
+| Name    | Width    | CSS                          |
+| ------- | -------- | ---------------------------- |
+| Mobile  | < 672px  | `@media (max-width: 671px)`  |
+| Tablet  | ≥ 672px  | `@media (min-width: 672px)`  |
+| Desktop | ≥ 992px  | `@media (min-width: 992px)`  |
+| Wide    | ≥ 1056px | `@media (min-width: 1056px)` |
+| X-Wide  | ≥ 1312px | `@media (min-width: 1312px)` |
+| XX-Wide | ≥ 1584px | `@media (min-width: 1584px)` |
+
+### Rules
+
+1. **Mobile-first**: Write base styles for mobile, add media queries for larger screens.
+2. Header nav items hide below 992px (burger menu shows).
+3. Side menu collapses to overlay below 992px.
+4. Footer top section stacks vertically below 992px.
+5. Modal widths are responsive (100% on mobile, percentage-based on desktop).
+
+---
+
+## Accessibility (a11y)
+
+### Required ARIA Attributes
+
+| Component     | Required ARIA                                                                 |
+| ------------- | ----------------------------------------------------------------------------- |
+| Button        | `aria-label` for icon-only buttons                                            |
+| Modal         | `role="dialog"`, `aria-modal="true"`, `aria-labelledby`                       |
+| Accordion     | `aria-expanded="true/false"` on trigger                                       |
+| Tabs          | `role="tablist"`, `role="tab"`, `aria-selected`                               |
+| Dropdown      | `aria-expanded`, `aria-haspopup="listbox"`, `role="listbox"`, `role="option"` |
+| Breadcrumbs   | `aria-label="Breadcrumb"`, `aria-current="page"` on last item                 |
+| Toast/Banner  | `role="alert"`                                                                |
+| Tooltip       | `role="tooltip"`, `aria-describedby` on trigger                               |
+| Spinner       | `aria-label="Loading"`, `role="img"`                                          |
+| Close buttons | `aria-label="Close"` or `aria-label="Dismiss"`                                |
+| Navigation    | `aria-label` on `<nav>` elements                                              |
+
+### Focus Management
+
+- All interactive elements have `:focus-visible` styles (2px solid blue-400 outline).
+- Focus outline uses `var(--color-foreground-border-accent-focus)`.
+- Modals should trap focus.
+- Side menu overlay closes on Escape.
+
+### Contrast
+
+- Use semantic tokens (they meet WCAG 2.1 AA contrast requirements).
+- Never override text colors with lighter alternatives.
+- `--color-foreground-text-strong` on `--color-background-base` = ≥4.5:1 ratio.
+
+---
+
+## Code Conventions
+
+### BEM Naming Pattern
+
+```
+.tl-{block}                    → Component root
+.tl-{block}__{element}         → Sub-part of component
+.tl-{block}--{modifier}        → Variant/state
+.tl-{block}__{element}--{mod}  → Element variant
+```
+
+### Class Order in HTML
+
+1. Base class first: `tl-button`
+2. Variant modifier: `tl-button--primary`
+3. Size modifier: `tl-button--md`
+4. State modifier: `tl-button--full-width`
+
+Example: `class="tl-button tl-button--primary tl-button--md tl-button--full-width"`
+
+### Rules
+
+1. **NEVER write custom CSS** if a Tegel Lite class already exists for the purpose.
+2. **NEVER use inline styles for colors, spacing, or any design properties.** ALWAYS use CSS classes with Tegel tokens.
+   - ❌ BAD: `<span style="background-color: var(--color-system-success-discrete);">Active</span>`
+   - ✅ GOOD: Create a CSS class `.status-badge--success { background-color: var(--color-system-success-discrete); }`
+3. **NEVER add inline styles to Tegel components.** If a component doesn't have the variant you need, create a custom component.
+4. **ALWAYS use semantic HTML** (`<button>`, `<a>`, `<nav>`, `<header>`, etc.).
+5. **ALWAYS wrap the app** in `<body class="scania tds-mode-light">`.
+6. When building custom components, use Tegel tokens for all colors, spacing, and typography.
+7. Keep custom CSS in separate files, never modify the Tegel Lite CSS files.