@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/palette/index.ts

@@ -0,0 +1,2 @@
+export type { PaletteColor } from './palette';
+export { PALETTE_COLORS, paletteTokens } from './palette';

package/src/palette/palette.ts

@@ -0,0 +1,108 @@
+/**
+ * Categorical color palette. 30 named colors with bg + fg pairs.
+ * Use for consumer-defined domain → color mappings (audit event
+ * namespaces, tag/label picker, team-colored checkboxes, …).
+ *
+ * NOT semantic — use `BadgeTone` (info/success/warning/danger/…)
+ * for status. Palette colors carry no meaning beyond visual identity.
+ *
+ * The generated `@eocrm/design-tokens` Sass contract exposes the
+ * `--color-palette-<name>-bg/--color-palette-<name>-fg` namespace.
+ * Contributors change source definitions in
+ * `packages/design-tokens/src/tokens.json`.
+ */
+export type PaletteColor =
+  | 'red'
+  | 'coral'
+  | 'orange'
+  | 'amber'
+  | 'gold'
+  | 'yellow'
+  | 'olive'
+  | 'lime'
+  | 'green'
+  | 'emerald'
+  | 'mint'
+  | 'teal'
+  | 'cyan'
+  | 'sky'
+  | 'blue'
+  | 'navy'
+  | 'indigo'
+  | 'violet'
+  | 'lavender'
+  | 'purple'
+  | 'plum'
+  | 'fuchsia'
+  | 'magenta'
+  | 'pink'
+  | 'rose'
+  | 'brown'
+  | 'taupe'
+  | 'slate'
+  | 'stone'
+  | 'charcoal';
+
+/**
+ * Ordered list of all 30 palette colors. Use for demo grids, color
+ * pickers, or anywhere a stable iteration order is needed.
+ */
+export const PALETTE_COLORS = [
+  'red',
+  'coral',
+  'orange',
+  'amber',
+  'gold',
+  'yellow',
+  'olive',
+  'lime',
+  'green',
+  'emerald',
+  'mint',
+  'teal',
+  'cyan',
+  'sky',
+  'blue',
+  'navy',
+  'indigo',
+  'violet',
+  'lavender',
+  'purple',
+  'plum',
+  'fuchsia',
+  'magenta',
+  'pink',
+  'rose',
+  'brown',
+  'taupe',
+  'slate',
+  'stone',
+  'charcoal',
+] as const satisfies readonly PaletteColor[];
+
+// Compile-time exhaustiveness: fails tsc if a PaletteColor member is missing from the array.
+null as unknown as PaletteColor satisfies (typeof PALETTE_COLORS)[number];
+
+/**
+ * Returns the CSS custom-property names for a palette color's bg and fg.
+ * Use to apply palette colors to consumer-built components without
+ * hard-coding the var names.
+ *
+ * @example
+ * const { bg, fg } = paletteTokens('amber');
+ * // bg === 'var(--color-palette-amber-bg)'
+ * // fg === 'var(--color-palette-amber-fg)'
+ *
+ * @example
+ * // In a consumer-built chip:
+ * function CategoryChip({ color, children }: { color: PaletteColor; children: ReactNode }) {
+ *   const { bg, fg } = paletteTokens(color);
+ *   return <span style={{ background: bg, color: fg }}>{children}</span>;
+ * }
+ */
+export function paletteTokens(color: PaletteColor): { bg: string; fg: string } {
+  return {
+    bg: `var(--color-palette-${color}-bg)`,
+    fg: `var(--color-palette-${color}-fg)`,
+  };
+}

package/src/styles/dark.scss

@@ -0,0 +1,4 @@
+// Package export subpaths include the extension; omitting it makes Sass
+// resolve the unexported "./styles/_dark" partial instead.
+// stylelint-disable-next-line scss/load-partial-extension
+@forward '@eocrm/design-tokens/styles/dark.scss';

package/src/styles/global.scss

@@ -0,0 +1,7 @@
+// Single global entry. Import this once from main.tsx.
+// Component-specific styles do NOT belong here — they go in *.module.scss next to the component.
+
+@use 'tokens';
+@use 'dark';
+@use 'reset';
+@use 'typography';

package/src/styles/mixins.scss

@@ -0,0 +1,143 @@
+// Mixins for use inside component .module.scss files via `@use '@styles/mixins' as *;`
+// NEVER includes raw colors or sizes — only structural patterns using tokens.
+
+// `outline`, not `box-shadow` (#505). The ring has to clear 3:1 against BOTH
+// things it touches — the surface outside it and the element fill inside it.
+// Against white and --color-accent that leaves almost nothing: 3:1 on white
+// caps relative luminance at 0.300, while 3:1 on #0052cc (L 0.1039) needs
+// L >= 0.412 to be the LIGHTER of the pair. Nothing satisfies both.
+// The one escape is the other side of that comparison — a ring DARKER than the
+// accent, L <= 0.0013 — and it is not a real option: that is black to three
+// decimal places (#000000 scores 21:1 and 3.08:1), it reads as 1.30:1 against
+// the dark theme's own background, and a black focus ring no longer tracks the
+// tone it belongs to, which is the relationship the ring gate exists to hold.
+// So the constraint is not literally unsatisfiable, but it is unsatisfiable by
+// any colour that is still a ring, and the colour was never the lever.
+// That argument is over OPAQUE rings. A translucent one composites to two
+// different effective colours over the two backdrops, so the single-luminance
+// reasoning does not reach it — but a sweep of alpha against an RGB grid over
+// both backdrops returns only near-blacks, and only at alpha 0.95 and above —
+// the same answer the opaque case gives, arrived at from the other direction.
+// Alpha was the thing #490 proposed raising, so it is worth saying it was
+// checked rather than assumed.
+// `outline-offset` is, and it is the native one. The gap shows whatever is
+// actually painted behind the element, so the ring is separated from the fill
+// it surrounds without the library naming that surface in a token — which a
+// two-layer box-shadow would have to, and would get wrong on every sunken panel
+// and inside every Modal.
+// "Whatever is behind" is not always a page surface: joined siblings (a visual
+// ButtonGroup of primary Buttons) put the NEIGHBOUR'S fill in the gap, where an
+// accent ring on an accent fill reads 1:1 along the shared edge. The other three
+// edges still land on the page, so the indicator is perceivable — but that one
+// edge is not, the four-surface gate cannot see it, and it is the one place this
+// mechanism does not fully solve.
+// A z-index lift does NOT help and was briefly added on the belief that it did:
+// within a stacking context an outline paints after all descendant backgrounds,
+// so the ring already draws over a joined neighbour with no lift at all. The
+// problem there is contrast, not paint order.
+// Outline also follows border-radius and leaves box-shadow free for the
+// element's own elevation, which this mixin
+// used to overwrite on focus. DataTable and HeaderCell ALREADY set
+// `outline-offset` next to this include before #505, and two DataTable rules —
+// the clickable row and the expand button — also wrote `outline: none`. All of
+// it inert against a box-shadow ring.
+// They were written expecting an outline; now they get one.
+// An outline IS clipped by an ancestor's overflow, exactly as a spread shadow
+// is — an earlier version of this comment claimed otherwise and the migration
+// then lost bands in three components before a browser sweep caught it. Where
+// the focusable sits flush against a clipping ancestor, draw the ring inset by
+// passing `$offset: calc(-1 * var(--ring-offset))` to the mixin — NOT a
+// separate `outline-offset` declaration after the `@include`, which only
+// re-adds the dead-declaration shape a `structure.test.ts` gate now bans (a
+// standalone `outline-offset` override used to be the pattern here; #513's
+// batch deleted it from every call site once `$offset` existed to replace it).
+// For the current set, grep `@include focus-ring(` under src/components and
+// read the `$offset` arguments. No count is written in prose here on
+// purpose: every attempt at one in this area has gone stale before the PR
+// that wrote it even shipped.
+// That trade is not free either. An inset ring paints over the element's
+// outermost pixels, including its own border, so check what that border
+// carries, and record what you find — the severity is not uniform, so do not
+// reason from one site to another. Calendar's TimedEvent loses the 1px tone
+// border and 1px of its 3px stripe gradient; OptionsPicker's group header has a
+// border exactly as wide as the band and loses it entirely. Both record their
+// own case in situ. Grep as above for the current set rather than trusting an
+// enumeration here.
+@mixin focus-ring($color: var(--ring-accent), $offset: var(--ring-offset)) {
+  outline: var(--ring-width) solid #{$color};
+  outline-offset: #{$offset};
+}
+
+@mixin visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@mixin truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// Two soft rings that grow OUTWARD from the host's edge and fade — an
+// "act here" cue (Tour click-to-continue, Highlight). Emits ::before/::after,
+// so the host must be positioned (relative/absolute/fixed) and must not use
+// its own pseudo-elements. Parameterised by colour so any caller can tint it;
+// the glow goes through color-mix() so a var() colour works.
+// Each including module gets one `attention-wave` keyframes block (CSS Modules
+// hash the name per file); per-host geometry reaches it through --wave-reach /
+// --wave-radius, set here, so every host in that module shares the block.
+// --wave-peak (0.9) is the rings' starting opacity — a motion constant of
+// this cue, not a theme value, so it is local rather than an --opacity-* token.
+// Reduced motion hides both rings; the caller supplies a static cue.
+@mixin attention-waves($color, $duration, $delay, $reach, $edge, $glow, $radius) {
+  --wave-reach: #{$reach};
+  --wave-radius: #{$radius};
+  --wave-peak: 0.9;
+
+  &::before,
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border: #{$edge} solid #{$color};
+    border-radius: inherit;
+    box-shadow: inset 0 0 #{$glow} calc(#{$glow} / 4) color-mix(in srgb, #{$color} 55%, transparent);
+    opacity: var(--opacity-hidden);
+    pointer-events: none;
+    animation: attention-wave #{$duration} cubic-bezier(0.2, 0.6, 0.4, 1) infinite;
+  }
+
+  &::after {
+    animation-delay: #{$delay};
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    &::before,
+    &::after {
+      display: none;
+    }
+  }
+
+  @at-root {
+    @keyframes attention-wave {
+      0% {
+        inset: 0;
+        opacity: var(--wave-peak);
+      }
+
+      100% {
+        inset: calc(-1 * var(--wave-reach));
+        opacity: var(--opacity-hidden);
+        border-radius: calc(var(--wave-radius) + var(--wave-reach));
+      }
+    }
+  }
+}

package/src/styles/reset.scss

@@ -0,0 +1,78 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+* {
+  margin: 0;
+
+  // Thin, theme-colored scrollbars instead of the chunky OS default, on every
+  // scroller in the library and in consumer code. The universal selector is
+  // deliberate: `scrollbar-color` inherits, `scrollbar-width` does NOT — set
+  // only on the root, nested scrollers keep a fat `auto` gutter painted in our
+  // thumb color. The color rides along on `*` rather than inheriting from the
+  // root so a subtree that retones `--color-fg-subtle` retones its scrollbars
+  // too. Specificity 0-0-0, so opt a scroller out with its own
+  // `scrollbar-width: auto` / `scrollbar-color: auto` — on the scroller itself,
+  // not an ancestor, since every descendant re-matches `*`. Unsupporting
+  // engines keep their default; overlay-scrollbar platforms (macOS) ignore the
+  // track color; forced-colors reverts the thumb to the system palette; and
+  // Chromium ignores `::-webkit-scrollbar` rules once these are set. Accepted
+  // trade-off: `thin` is a smaller drag target than the OS bar, below WCAG
+  // 2.5.8's 24px.
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-fg-subtle) transparent;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  font-family: var(--font-family-sans);
+  font-size: var(--font-size-md);
+  line-height: var(--line-height-normal);
+  color: var(--color-fg);
+
+  // Matches the base beneath Screen and AppLayout so sibling route swaps do
+  // not expose a contrasting frame. Consumers can retone the document without
+  // replacing the reset rule by overriding the global token.
+  background: var(--document-background, var(--color-bg-subtle));
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+
+input,
+button,
+textarea,
+select {
+  font: inherit;
+  color: inherit;
+}
+
+p,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  overflow-wrap: break-word;
+}
+
+button {
+  background: none;
+  border: none;
+  padding: 0;
+}

package/src/styles/tokens.scss

@@ -0,0 +1,18 @@
+// Emit Badge component aliases at the global level so consumers can
+// reference them without first rendering a Badge.
+@use '../components/Badge/Badge.tokens';
+
+// Sticky defaults must load with the global token entry rather than when the
+// component first mounts, so same-specificity consumer :root overrides have
+// stable source order.
+@use '../components/Sticky/Sticky.tokens';
+
+// TableOfContents reads Sticky's --sticky-top-topbar, so its tokens @use
+// Sticky's; emitting them here keeps that re-emission in the same stable
+// global source order instead of a lazily loaded component stylesheet.
+@use '../components/TableOfContents/TableOfContents.tokens';
+
+// Package export subpaths include the extension; omitting it makes Sass
+// resolve the unexported "./styles/_tokens" partial instead.
+// stylelint-disable-next-line scss/load-partial-extension
+@forward '@eocrm/design-tokens/styles/tokens.scss';

package/src/styles/typography.scss

@@ -0,0 +1,44 @@
+h1 {
+  font-size: var(--font-size-3xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-tight);
+}
+
+h2 {
+  font-size: var(--font-size-2xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-tight);
+}
+
+h3 {
+  font-size: var(--font-size-lg);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-tight);
+}
+
+h4 {
+  font-size: var(--font-size-md);
+  font-weight: var(--font-weight-semibold);
+}
+
+a {
+  color: var(--color-accent);
+  text-decoration: none;
+}
+
+// Specificity 0,0,1 (ties the at-rest `a` rule above, wins by source order)
+// via :where() around only the `:hover` part — so this never outranks a
+// component's own single-class rule (e.g. `.link:hover`, `.button:hover`,
+// `.linkCard:hover`, all 0,1,0), but still beats the at-rest `a` rule so the
+// hover underline actually applies. A fully zero-specificity `:where(a:hover)`
+// (0,0,0) loses to the at-rest `a { text-decoration: none }` (0,0,1) and never
+// shows at all — see #584/#592.
+a:where(:hover) {
+  text-decoration: underline;
+}
+
+code,
+pre {
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-code);
+}