@danjelp/ngx-app-shell 1.0.0

package/src/lib/styles/_tokens.scss

@@ -0,0 +1,340 @@
+@use 'sass:list';
+@use 'sass:map';
+
+/// Single source of truth for the shell's design tokens.
+///
+/// Three layers, each overriding the one below:
+///
+///   1. global tokens     `--shell-surface`, `--shell-accent` …   ($shell-tokens)
+///   2. component tokens  `--shell-topbar-bg`, `--shell-drawer-duration` …
+///                        ($shell-component-tokens, fall back to layer 1)
+///   3. presets           `appearance` / `motion` config, bound as host
+///                        attributes; they only change layer-2 *defaults*, so
+///                        any component token still wins.
+///
+/// Every value is used as the inline fallback inside the components, so the
+/// shell renders correctly with no global stylesheet at all.
+$shell-tokens: (
+  // ── Structure ───────────────────────────────────────────────────────────
+  'topbar-height': 64px,
+  'topbar-padding-inline': 12px,
+  'topbar-gap': 8px,
+  'sidebar-width': 264px,
+  'sidebar-collapsed-width': 68px,
+  'sidebar-overlay-width': min(88vw, 320px),
+  'sidebar-padding': 12px,
+  'sidebar-gap': 2px,
+  'footer-min-height': 48px,
+  'main-padding': 24px,
+  'main-max-width': none,
+
+  // ── Surfaces & text ────────────────────────────────────────────────────
+  'color-scheme': light,
+  'surface': #ffffff,
+  'surface-raised': #f7f7f8,
+  'sidebar-surface': #fafafb,
+  'topbar-surface': #ffffff,
+  'fg': #1b1c1f,
+  'fg-muted': #6b6f76,
+  'border': #e6e6e9,
+  'hover-surface': #f0f0f3,
+  'active-surface': #e9e9ee,
+  'accent': #4f46e5,
+  'accent-fg': #ffffff,
+  'accent-surface': #eef0fe,
+  'focus-ring': #4f46e5,
+  'scrim': rgb(15 17 21 / 45%),
+  'shadow-panel': 0 12px 32px -12px rgb(15 17 21 / 28%),
+
+  // ── Shape, rhythm, motion ──────────────────────────────────────────────
+  'radius': 10px,
+  'radius-sm': 6px,
+  'nav-item-height': 36px,
+  'nav-item-gap': 10px,
+  'nav-icon-size': 18px,
+  'font-family': inherit,
+  'font-size': 14px,
+  'font-size-sm': 12.5px,
+  'transition-duration': 180ms,
+  'transition-easing': cubic-bezier(0.2, 0, 0, 1),
+
+  // ── Stacking ───────────────────────────────────────────────────────────
+  'z-main': 0,
+  'z-topbar': 20,
+  'z-scrim': 30,
+  'z-sidebar': 40,
+  'z-flyout': 50,
+  'z-skip-link': 60
+);
+
+/// Overrides for a dark theme. Only colour tokens change.
+$shell-dark-tokens: (
+  'color-scheme': dark,
+  'surface': #111215,
+  'surface-raised': #16171b,
+  'sidebar-surface': #141519,
+  'topbar-surface': #111215,
+  'fg': #ececf1,
+  'fg-muted': #9a9ca6,
+  'border': #26272d,
+  'hover-surface': #1d1e23,
+  'active-surface': #26272d,
+  'accent': #8f8aff,
+  'accent-fg': #0d0d12,
+  'accent-surface': rgb(143 138 255 / 16%),
+  'focus-ring': #8f8aff,
+  'scrim': rgb(0 0 0 / 60%),
+  'shadow-panel': 0 16px 40px -12px rgb(0 0 0 / 70%)
+);
+
+/// `tok('sidebar-width')` → `var(--shell-sidebar-width, 264px)`
+/// Errors on unknown names, so a typo fails the build instead of silently
+/// resolving to an empty value.
+@function tok($name) {
+  @if not map.has-key($shell-tokens, $name) {
+    @error "Unknown shell token '#{$name}'. Known tokens: #{map.keys($shell-tokens)}.";
+  }
+  @return var(--shell-#{$name}, #{map.get($shell-tokens, $name)});
+}
+
+/// Raw default, without the `var()` wrapper.
+@function raw($name) {
+  @return map.get($shell-tokens, $name);
+}
+
+/// Per-part tokens. Each defaults to a global token.
+///
+/// Deliberately NOT emitted by `tokens()`: a custom property whose value is
+/// another `var()` is resolved where it is declared, so a `:root` alias would
+/// freeze the global value at `:root` and a theme class further down could no
+/// longer reach the part. The aliases therefore live only as fallbacks inside
+/// the components, where they resolve against the component's own cascade.
+/// Setting a *concrete* value anywhere (`:root { --shell-topbar-bg: #0b1020 }`)
+/// is exactly how they are meant to be used.
+$shell-component-tokens: (
+  // ── Shell (the container behind every part) ────────────────────────────
+  // Shows wherever a part is transparent or inset: transparent topbar,
+  // minimal footer, floating-sidebar gaps, the margin of an inset main.
+  'bg': tok('surface'),
+
+  // ── Topbar ─────────────────────────────────────────────────────────────
+  'topbar-bg': tok('topbar-surface'),
+  'topbar-fg': tok('fg'),
+  // Border tokens take the CSS shorthand — 1 to 4 values, top right bottom
+  // left — so each side can differ: `--shell-topbar-border-width: 0 0 2px`.
+  'topbar-border-width': 0 0 1px,
+  'topbar-border-style': solid,
+  'topbar-border-color': tok('border'),
+  'topbar-radius': 0px,
+  'topbar-shadow': none,
+  'topbar-blur': 12px,
+
+  // ── Sidebar (persistent panel and rail) ────────────────────────────────
+  'sidebar-bg': tok('sidebar-surface'),
+  'sidebar-fg': tok('fg'),
+  'sidebar-border-color': tok('border'),
+  'sidebar-shadow': none,
+  'sidebar-radius': 0px,
+  'sidebar-inset': 8px,
+  'sidebar-peek-shadow': tok('shadow-panel'),
+
+  // ── Drawer (overlay mode) and its scrim ────────────────────────────────
+  'drawer-bg': var(--shell-sidebar-bg, #{tok('sidebar-surface')}),
+  'drawer-shadow': tok('shadow-panel'),
+  'drawer-radius': 0px,
+  'drawer-scrim': tok('scrim'),
+  'drawer-scrim-blur': 0px,
+
+  // ── Navigation ─────────────────────────────────────────────────────────
+  'nav-item-fg': tok('fg'),
+  'nav-item-hover-bg': tok('hover-surface'),
+  'nav-item-active-bg': tok('accent-surface'),
+  'nav-item-active-fg': tok('accent'),
+  'nav-item-radius': tok('radius-sm'),
+  'nav-indicator-color': tok('accent'),
+  'nav-indicator-size': 3px,
+  'nav-heading-fg': tok('fg-muted'),
+  'nav-heading-size': tok('font-size-sm'),
+
+  // ── Topbar overflow (⋯) menu ───────────────────────────────────────────
+  'menu-bg': tok('surface'),
+  'menu-border-color': tok('border'),
+  'menu-shadow': tok('shadow-panel'),
+  'menu-radius': tok('radius'),
+
+  // ── Main & footer ──────────────────────────────────────────────────────
+  'main-bg': tok('surface'),
+  'main-fg': tok('fg'),
+  'main-border-width': 0,
+  'main-border-style': solid,
+  'main-border-color': tok('border'),
+  'main-radius': 0px,
+  'main-shadow': none,
+  'main-margin': 0,
+  'footer-bg': tok('surface-raised'),
+  'footer-fg': tok('fg-muted'),
+  'footer-border-color': tok('border'),
+  'footer-shadow': none,
+  'footer-font-size': tok('font-size-sm'),
+
+  // ── Frame: the rounded card of the `inset` layout ──────────────────────
+  // Wraps topbar, main and footer. Its radius and shadow give the card its
+  // shape; the parts inside keep their own tokens.
+  'frame-bg': tok('surface'),
+  'frame-border-width': 0,
+  'frame-border-style': solid,
+  'frame-border-color': tok('border'),
+  'frame-radius': 14px,
+  'frame-shadow': (0 1px 2px rgb(0 0 0 / 4%), 0 8px 24px -8px rgb(0 0 0 / 14%)),
+  'frame-inset': 8px,
+
+  // ── Subheader: the breadcrumb row ──────────────────────────────────────
+  // Its height is reserved (a minimum), so late labels and actions never
+  // shift the page.
+  'subheader-height': 44px,
+  'subheader-bg': tok('surface'),
+  'subheader-fg': tok('fg'),
+  'subheader-border-width': 0 0 1px,
+  'subheader-border-style': solid,
+  'subheader-border-color': tok('border'),
+  'subheader-padding-inline': 24px,
+  'subheader-shadow': none,
+  'subheader-radius': 0px,
+  // A margin plus radius/border/shadow gives an inset, pill-shaped row.
+  'subheader-margin': 0,
+  'subheader-font-size': tok('font-size'),
+
+  // ── Breadcrumb trail ───────────────────────────────────────────────────
+  'breadcrumb-fg': tok('fg-muted'),
+  'breadcrumb-hover-fg': tok('fg'),
+  'breadcrumb-current-fg': tok('fg'),
+  'breadcrumb-separator-color': tok('fg-muted'),
+  'breadcrumb-gap': 4px,
+  'breadcrumb-skeleton-bg': tok('active-surface'),
+  // `1em` = the row's font size, so `subheader-font-size` carries through.
+  'breadcrumb-font-size': 1em,
+  'breadcrumb-current-weight': 600,
+  'breadcrumb-hover-bg': tok('hover-surface'),
+  // Longest label before it truncates with an ellipsis.
+  'breadcrumb-label-max': 28ch
+);
+
+/// `ctok('topbar-bg')` → `var(--shell-topbar-bg, var(--shell-topbar-surface, #fff))`
+/// Pass `$fallback` to change the default for one preset while keeping the
+/// component token in charge: `ctok('topbar-shadow', $elevated-shadow)`.
+@function ctok($name, $fallback: null) {
+  @if not map.has-key($shell-component-tokens, $name) {
+    @error "Unknown shell component token '#{$name}'. Known: #{map.keys($shell-component-tokens)}.";
+  }
+  $default: map.get($shell-component-tokens, $name);
+  @if $fallback != null {
+    $default: $fallback;
+  }
+  @return var(--shell-#{$name}, #{$default});
+}
+
+/// Emit the global tokens as declarations. Include once in a global
+/// stylesheet if you want them inspectable in devtools or inheritable by your
+/// own components:
+///
+/// ```scss
+/// @use 'app-shell/styles/tokens' as shell;
+/// @include shell.tokens;                    // :root
+/// @include shell.tokens('.theme-compact');  // scoped variant
+/// ```
+@mixin tokens($selector: ':root') {
+  #{$selector} {
+    @each $name, $value in $shell-tokens {
+      --shell-#{$name}: #{$value};
+    }
+  }
+}
+
+/// Emit the dark palette under a selector of your choice:
+///
+/// ```scss
+/// @include shell.dark-tokens(':root[data-theme="dark"]');
+/// ```
+@mixin dark-tokens($selector) {
+  #{$selector} {
+    @each $name, $value in $shell-dark-tokens {
+      --shell-#{$name}: #{$value};
+    }
+  }
+}
+
+// ── Motion ────────────────────────────────────────────────────────────────
+
+/// Parts whose timing can be tuned on its own with
+/// `--shell-<scope>-duration` / `--shell-<scope>-easing`.
+///
+///   topbar      hover and preset changes in the bar
+///   sidebar     hover, peek shadow, colours of the panel
+///   collapse    rail ⇄ panel width (grid track, panel, peek)
+///   drawer      overlay drawer and scrim
+///   nav         nav item hover / active colours
+///   nav-expand  opening and closing sections
+///   menu        ⋯ overflow menus
+///   subheader   breadcrumb row and trail
+///   footer      footer colour changes
+$shell-motion-scopes: ('topbar', 'sidebar', 'collapse', 'drawer', 'nav', 'nav-expand', 'menu', 'subheader', 'footer');
+
+@function _check-scope($scope) {
+  @if $scope != null and not list.index($shell-motion-scopes, $scope) {
+    @error "Unknown motion scope '#{$scope}'. Known scopes: #{$shell-motion-scopes}.";
+  }
+  @return $scope;
+}
+
+/// Duration for a scope, multiplied by `--shell-motion-scale` — written by
+/// `<app-shell>` from `motion.speed`, and 0 when `motion.enabled` is false.
+/// That one factor gives a global switch and speed control that also governs
+/// durations an app sets per part.
+@function duration($scope: null) {
+  $value: tok('transition-duration');
+  @if _check-scope($scope) != null {
+    $value: var(--shell-#{$scope}-duration, #{$value});
+  }
+  @return calc(#{$value} * var(--shell-motion-scale, 1));
+}
+
+@function easing($scope: null) {
+  $value: tok('transition-easing');
+  @if _check-scope($scope) != null {
+    $value: var(--shell-#{$scope}-easing, #{$value});
+  }
+  @return $value;
+}
+
+/// `@include motion('drawer', transform, opacity);`
+@mixin motion($scope, $properties...) {
+  transition-property: $properties;
+  transition-duration: duration($scope);
+  transition-timing-function: easing($scope);
+
+  @media (prefers-reduced-motion: reduce) {
+    transition-duration: 1ms;
+  }
+}
+
+/// Global timing, no scope.
+@mixin transition($properties...) {
+  @include motion(null, $properties...);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+@mixin focus-ring($offset: 2px) {
+  &:focus-visible {
+    outline: 2px solid tok('focus-ring');
+    outline-offset: $offset;
+  }
+}
+
+/// Truncate a label that may be squeezed by a shrinking container.
+@mixin truncate {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}

package/styles/_tokens.scss

@@ -0,0 +1,3 @@
+// Stable public path for the token API:
+//   @use '@danjelp/ngx-app-shell/styles/tokens' as shell;
+@forward '../src/lib/styles/tokens';