@slotted/styles 0.0.0-stage → 0.1.0-beta.1

package/src/side-navigation/side-navigation.tokens.json

@@ -0,0 +1,87 @@
+[
+  "--slotted-app-shell-row-font-size",
+  "--slotted-app-shell-row-gap",
+  "--slotted-app-shell-row-height",
+  "--slotted-app-shell-row-inset",
+  "--slotted-app-shell-row-line-height",
+  "--slotted-app-shell-row-mark",
+  "--slotted-border-subtle",
+  "--slotted-border-width-thin",
+  "--slotted-control-font-family",
+  "--slotted-control-gap-lg",
+  "--slotted-control-gap-md",
+  "--slotted-control-gap-sm",
+  "--slotted-control-height-lg",
+  "--slotted-control-height-md",
+  "--slotted-control-height-sm",
+  "--slotted-control-icon-size-lg",
+  "--slotted-control-icon-size-md",
+  "--slotted-control-icon-size-sm",
+  "--slotted-control-transition-duration",
+  "--slotted-control-transition-easing",
+  "--slotted-current-edge",
+  "--slotted-disabled-foreground",
+  "--slotted-duration-instant",
+  "--slotted-duration-medium",
+  "--slotted-duration-short",
+  "--slotted-easing-enter",
+  "--slotted-easing-exit",
+  "--slotted-easing-standard",
+  "--slotted-focus-ring-color",
+  "--slotted-focus-ring-offset",
+  "--slotted-focus-ring-width",
+  "--slotted-font-size-md",
+  "--slotted-font-size-sm",
+  "--slotted-font-size-xs",
+  "--slotted-font-weight-medium",
+  "--slotted-font-weight-regular",
+  "--slotted-font-weight-semibold",
+  "--slotted-line-height-md",
+  "--slotted-line-height-sm",
+  "--slotted-line-height-xs",
+  "--slotted-radius-full",
+  "--slotted-radius-lg",
+  "--slotted-radius-md",
+  "--slotted-shadow-md",
+  "--slotted-side-navigation-active-background",
+  "--slotted-side-navigation-color",
+  "--slotted-side-navigation-current-background",
+  "--slotted-side-navigation-current-color",
+  "--slotted-side-navigation-current-description-color",
+  "--slotted-side-navigation-current-edge",
+  "--slotted-side-navigation-description-color",
+  "--slotted-side-navigation-description-gap",
+  "--slotted-side-navigation-dot-color",
+  "--slotted-side-navigation-dot-size",
+  "--slotted-side-navigation-flyout-border-color",
+  "--slotted-side-navigation-flyout-measure",
+  "--slotted-side-navigation-flyout-min-measure",
+  "--slotted-side-navigation-flyout-radius",
+  "--slotted-side-navigation-flyout-shadow",
+  "--slotted-side-navigation-flyout-surface",
+  "--slotted-side-navigation-guide-color",
+  "--slotted-side-navigation-hover-background",
+  "--slotted-side-navigation-hover-color",
+  "--slotted-side-navigation-indent",
+  "--slotted-side-navigation-indent-step",
+  "--slotted-side-navigation-radius",
+  "--slotted-side-navigation-row-gap",
+  "--slotted-side-navigation-section-color",
+  "--slotted-side-navigation-section-gap",
+  "--slotted-side-navigation-section-label-gap",
+  "--slotted-space-1",
+  "--slotted-space-2",
+  "--slotted-space-3",
+  "--slotted-space-4",
+  "--slotted-space-5",
+  "--slotted-space-7",
+  "--slotted-surface-raised",
+  "--slotted-text",
+  "--slotted-text-muted",
+  "--slotted-tone-accent-solid",
+  "--slotted-tone-accent-surface",
+  "--slotted-tone-accent-text",
+  "--slotted-tone-secondary-subtle-active",
+  "--slotted-tone-secondary-subtle-hover",
+  "--slotted-z-index-popover"
+]

package/src/skeleton/skeleton.css

@@ -0,0 +1,431 @@
+@layer slotted.components {
+  /* ── The box, and the row inside a paragraph ────────────────────────────
+   *
+   * One fill, one rim, one highlight, shared by the standalone placeholder and
+   * by every line of a text placeholder. They are the same object drawn at two
+   * scales, so they resolve their paint in one place.
+   *
+   * `--slotted-disabled-background` is the fill because it already means the
+   * one thing a placeholder means: a surface that is not available yet. It
+   * carries a cost, and the rim is what pays it — in the `high-contrast`
+   * scheme that token is the page's own white, so a fill alone would be an
+   * invisible box. `--slotted-border-subtle` is the fill's own colour in
+   * light, a faint step in dark, and black in high contrast: a rim that
+   * appears exactly where the fill stops working and adds no noise where it
+   * does.
+   */
+  /**
+   * `[data-loading]` on the paint rather than on the geometry, and the
+   * difference is not cosmetic: `user-select` and `color` inherit, so a
+   * placeholder that kept them after the content arrived handed the consumer
+   * unselectable, invisible text. The first capture of this family showed a
+   * loaded row as an empty line beside its avatar for exactly that reason.
+   * Geometry is left unguarded because a loaded placeholder is
+   * `display: contents` and has no box for it to describe.
+   */
+  [data-ui='skeleton'][data-part='root'][data-loading],
+  [data-ui='skeleton'][data-part='text'][data-loading] [data-part='line'] {
+    /**
+     * The unavailable surface, pushed a little toward the text colour. The
+     * token alone is not enough and the first dark capture is why: in the dark
+     * scheme `--slotted-disabled-background` is `#18181b` over a `#131316`
+     * ground, one step apart, and a page of placeholders read as an empty
+     * page. Mixing toward `--slotted-text` moves away from the ground in every
+     * scheme, because the text colour is the far end of each scheme's own
+     * range — darker in light, lighter in dark, black in high contrast.
+     *
+     * Eight per cent, measured rather than chosen. In oklab lightness the
+     * unmixed token sits 0.071 from the light surface, 0.022 from the dark one
+     * and 0.000 from the high-contrast one; at this ratio the three are 0.129,
+     * 0.086 and 0.081, which is the closest the one number gets to treating
+     * the three schemes alike without making the light placeholder shout. For
+     * scale, MUI's light skeleton sits about 0.07 from its ground.
+     */
+    --_fill: var(
+      --slotted-skeleton-fill,
+      color-mix(
+        in oklab,
+        var(--slotted-disabled-background, ButtonFace) 92%,
+        var(--slotted-text, CanvasText)
+      )
+    );
+    --_edge: var(--slotted-skeleton-border-color, var(--slotted-border-subtle, ButtonBorder));
+    /**
+     * A shimmer needs a second colour, and in August this family declined to
+     * have one on the grounds that the theme did not own it. It does: the band
+     * is the fill carried further along the same axis the fill was derived on,
+     * so it separates from the fill in every scheme without a token of its own.
+     * The band is darker than the fill in light and lighter in dark, which is
+     * Ant Design's answer to the same problem — its gradient runs from
+     * `rgba(0,0,0,.06)` to `rgba(0,0,0,.15)` — and it is the only direction
+     * that is a direction at all in three schemes rather than two.
+     */
+    --_highlight: var(
+      --slotted-skeleton-highlight-color,
+      color-mix(in oklab, var(--_fill) 86%, var(--slotted-text, CanvasText))
+    );
+    /**
+     * The dimmed end of the pulse: the fill carried toward the deepest surface
+     * the scheme holds, so it is a step away from the fill in every scheme
+     * without a token of its own. `surface-sunken` rather than `surface`
+     * because the two are the same white in light and a full step apart in
+     * dark, which is where the pulse was too quiet to see.
+     *
+     * A colour rather than an opacity, and that is a correction rather than a
+     * preference. The pulse used to fade the whole box, which flickered in the
+     * dark scheme: the rim faded with the fill, so once every cycle the shape
+     * came within a hair of the ground and then came back. Painting the
+     * background alone leaves the rim at full strength, and the box never
+     * leaves the page.
+     */
+    --_trough: var(
+      --slotted-skeleton-trough-color,
+      color-mix(in oklab, var(--_fill) 60%, var(--slotted-surface-sunken, Canvas))
+    );
+    background-color: var(--_fill);
+    border: var(--slotted-skeleton-border-width, var(--slotted-border-width-thin, 1px)) solid
+      var(--_edge);
+    /* The rim is inside the reserved geometry, or the placeholder is two
+       pixels taller than the content it stands for. */
+    box-sizing: border-box;
+    /* A placeholder is furniture, not text: nothing in it should be
+       selectable, and a drag across a loading list should not highlight it. */
+    user-select: none;
+  }
+
+  /* ── Shapes ─────────────────────────────────────────────────────────────
+   *
+   * Four relationships to the surrounding layout rather than four points on
+   * one scale: a line of type, a block of content, and the two boxes an avatar
+   * can be.
+   */
+
+  [data-ui='skeleton'][data-part='root'] {
+    display: inline-block;
+    /* Never a negative or zero box, whatever the consumer's value resolves
+       to. A placeholder that cannot be seen cannot be corrected. */
+    min-block-size: var(--slotted-skeleton-border-width, var(--slotted-border-width-thin, 1px));
+  }
+
+  /**
+   * A bar the height of the type it is placed in, sitting on that type's
+   * optical centre rather than on its baseline — the correction `link` derives
+   * for the marker it draws beside a word, for the same reason: an inline box
+   * is aligned by its bottom edge, and centring it on the cap line is what
+   * puts it where the reader expects the word to be.
+   *
+   * There is no size axis here on purpose. `1em` is the size of whatever type
+   * surrounds it, at whatever density, including a scale this library does not
+   * own — an axis would have been a coarser second copy of the type scale that
+   * a consumer could set to the wrong value.
+   */
+  [data-ui='skeleton'][data-part='root'][data-shape='text'] {
+    --_line: var(--slotted-skeleton-line-size, 1cap);
+
+    block-size: var(--slotted-skeleton-block-size, var(--_line));
+    border-radius: var(--slotted-radius-full, 9999px);
+    inline-size: var(--slotted-skeleton-inline-size, 100%);
+    /**
+     * Zero for the default bar, and that is the point rather than an accident:
+     * a box one cap tall, aligned on the baseline, occupies exactly the band a
+     * capital letter occupies. The expression stays because a consumer who
+     * overrides the height still wants it centred on the same band.
+     */
+    vertical-align: calc(0.5cap - 0.5 * var(--_line));
+  }
+
+  /**
+   * The block of content: an image, a chart, a map, a card. Its height is the
+   * consumer's or its content's, and with neither it is one line tall — a
+   * placeholder that resolved to nothing would be a hole in the page that no
+   * capture and no reader could point at.
+   */
+  [data-ui='skeleton'][data-part='root'][data-shape='block'] {
+    block-size: var(--slotted-skeleton-block-size, auto);
+    border-radius: var(--slotted-skeleton-radius, var(--slotted-radius-md, 6px));
+    display: block;
+    inline-size: var(--slotted-skeleton-inline-size, 100%);
+    min-block-size: var(--slotted-skeleton-min-block-size, 1lh);
+  }
+
+  /**
+   * The two shapes an avatar can be, taking Avatar's own two words and Avatar's
+   * own scale. `--slotted-skeleton-size` is the unstepped escape hatch `icon`
+   * established and `avatar` reuses, and it is the family's own rather than
+   * `--slotted-avatar-size`: setting it on a container must not resize the real
+   * avatars standing beside the placeholders.
+   */
+  [data-ui='skeleton'][data-part='root'][data-shape='circle'],
+  [data-ui='skeleton'][data-part='root'][data-shape='square'] {
+    --_size: var(--slotted-skeleton-size, var(--slotted-avatar-size-md, 36px));
+
+    block-size: var(--slotted-skeleton-block-size, var(--_size));
+    inline-size: var(--slotted-skeleton-inline-size, var(--_size));
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-shape='circle'] {
+    border-radius: var(--slotted-radius-full, 9999px);
+  }
+
+  /**
+   * A sixth of the box, which is the proportion `avatar` derives rather than a
+   * step of the radius scale: six pixels is a gentle round on a 64-pixel square
+   * and a quarter-circle on a 20-pixel one.
+   */
+  [data-ui='skeleton'][data-part='root'][data-shape='square'] {
+    border-radius: var(--slotted-skeleton-radius, calc(var(--_size) / 6));
+  }
+
+  /* ── The size steps, which mean something only for the two round shapes ── */
+
+  [data-ui='skeleton'][data-part='root'][data-shape='circle'][data-size='xs'],
+  [data-ui='skeleton'][data-part='root'][data-shape='square'][data-size='xs'] {
+    --_size: var(--slotted-skeleton-size, var(--slotted-avatar-size-xs, 24px));
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-shape='circle'][data-size='sm'],
+  [data-ui='skeleton'][data-part='root'][data-shape='square'][data-size='sm'] {
+    --_size: var(--slotted-skeleton-size, var(--slotted-avatar-size-sm, 28px));
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-shape='circle'][data-size='md'],
+  [data-ui='skeleton'][data-part='root'][data-shape='square'][data-size='md'] {
+    --_size: var(--slotted-skeleton-size, var(--slotted-avatar-size-md, 36px));
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-shape='circle'][data-size='lg'],
+  [data-ui='skeleton'][data-part='root'][data-shape='square'][data-size='lg'] {
+    --_size: var(--slotted-skeleton-size, var(--slotted-avatar-size-lg, 48px));
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-shape='circle'][data-size='xl'],
+  [data-ui='skeleton'][data-part='root'][data-shape='square'][data-size='xl'] {
+    --_size: var(--slotted-skeleton-size, var(--slotted-avatar-size-xl, 64px));
+  }
+
+  /* ── The placeholder that covers real content ───────────────────────────
+   *
+   * The only form in which the reserved geometry cannot disagree with what
+   * replaces it, because it is that content's own geometry. MUI infers the box
+   * from `children` and Spectrum clones the child with a skeleton class; both
+   * arrive here, and neither hides the text a bare text node carries.
+   *
+   * `:not(:empty)` is what tells the two apart, so no attribute has to be
+   * invented for a fact the DOM already states. Every stated size stays
+   * available: a consumer covering a paragraph that has not been measured
+   * still sets one.
+   */
+  [data-ui='skeleton'][data-part='root'][data-loading]:not(:empty) {
+    block-size: var(--slotted-skeleton-block-size, auto);
+    /* An element child is hidden by `visibility`; a bare text node is not an
+       element and can only be hidden by taking the colour away. */
+    color: transparent;
+    inline-size: var(--slotted-skeleton-inline-size, auto);
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-loading]:not(:empty) > * {
+    visibility: hidden;
+  }
+
+  /* ── The paragraph ──────────────────────────────────────────────────────
+   *
+   * Rows of exactly one line box, so `n` rows occupy exactly the `n` lines of
+   * the paragraph they stand in and nothing moves when the words arrive. Every
+   * surveyed implementation types a pixel height here instead and is therefore
+   * wrong at every density but one.
+   *
+   * The bar inside the row is one cap rather than one em, which is the second
+   * half of the same idea and was found by measuring rather than by reading:
+   * at `1em` the bar filled sixteen pixels of a twenty-pixel line box, and a
+   * paragraph of them read as a barcode because real prose fills a little over
+   * half its leading. A capital's height is where the ink actually is.
+   */
+  [data-ui='skeleton'][data-part='text'] {
+    align-items: center;
+    display: grid;
+    grid-auto-rows: var(--slotted-skeleton-row-size, 1lh);
+    inline-size: var(--slotted-skeleton-inline-size, 100%);
+  }
+
+  [data-ui='skeleton'] [data-part='line'] {
+    block-size: var(--slotted-skeleton-line-size, 1cap);
+    border-radius: var(--slotted-radius-full, 9999px);
+    inline-size: 100%;
+  }
+
+  /**
+   * The short last line is what makes a stack of bars read as prose rather
+   * than as a barcode. `:not(:only-child)` is the case Chakra guards in
+   * TypeScript and Carbon does not guard at all: one line shortened by itself
+   * stands for a sentence that was never there.
+   */
+  [data-ui='skeleton'] [data-part='line']:last-child:not(:only-child) {
+    inline-size: var(--slotted-skeleton-last-line-size, 62%);
+  }
+
+  /* ── Loaded ─────────────────────────────────────────────────────────────
+   *
+   * The element stays and stops taking part in layout, so the content it was
+   * covering lands exactly where it would have landed with no placeholder at
+   * all — and an empty placeholder, having nothing to lay out, renders
+   * nothing. One declaration answers both, and neither answer remounts the
+   * consumer's content on the way through.
+   */
+  [data-ui='skeleton'][data-part='root']:not([data-loading]),
+  [data-ui='skeleton'][data-part='text']:not([data-loading]) {
+    display: contents;
+  }
+
+  /* ── The region ─────────────────────────────────────────────────────────
+   *
+   * A region stands for a block of content, so it takes the inline size of
+   * whatever holds it. Without this it is a flex item with no definite size,
+   * and a flex item that shrinks to its content while the placeholders inside
+   * it are a percentage of that content resolves to nothing: measured at two
+   * pixels inside a 599-pixel column, every placeholder in it two pixels wide.
+   * The token is the way out for a region that really is inline.
+   */
+  [data-ui='skeleton'][data-part='region'] {
+    inline-size: var(--slotted-skeleton-inline-size, 100%);
+    min-inline-size: 0;
+  }
+
+  /* ── Motion ─────────────────────────────────────────────────────────────
+   *
+   * Both loops run on a layer drawn over the fill, and animate only `opacity`
+   * and `transform`, which the compositor runs without the page. The first
+   * version animated a registered, inherited custom property, which restyled
+   * every placeholder — and every descendant of a region — on every frame:
+   * on the docs' data-grid page the 72 boxes of one loading grid took 2.7
+   * seconds of style in every 3 with nothing else moving.
+   *
+   * The layer sits inside the rim (`inset: 0` of an absolute box is the
+   * padding box), and the box clips it to its own corners, so neither loop
+   * touches the edge or the outline of the shape.
+   *
+   * Boxes drawn in one render start their loops in one frame and move as one
+   * surface. A box mounted later starts its own cycle; `--slotted-skeleton-phase`
+   * (0 to 1, a point in the cycle) is where a box starts, so a consumer that
+   * needs a late box in step, and a capture that needs one moment, can name it.
+   */
+  [data-ui='skeleton'][data-part='root'][data-loading]:not([data-animation='none']),
+  [data-ui='skeleton'][data-part='text'][data-loading]:not([data-animation='none'])
+    [data-part='line'] {
+    overflow: clip;
+    position: relative;
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-animation='pulse'][data-loading]::after,
+  [data-ui='skeleton'][data-part='root'][data-animation='shimmer'][data-loading]::after,
+  [data-ui='skeleton'][data-animation='pulse'][data-loading] [data-part='line']::after,
+  [data-ui='skeleton'][data-animation='shimmer'][data-loading] [data-part='line']::after {
+    animation-delay: calc(
+      var(--slotted-skeleton-phase, 0) * var(--slotted-duration-loop-slow) * -1
+    );
+    animation-duration: var(--slotted-duration-loop-slow);
+    animation-iteration-count: infinite;
+    content: '';
+    inset-block: 0;
+    inset-inline: 0;
+    pointer-events: none;
+    position: absolute;
+  }
+
+  /**
+   * The quiet one: the trough laid over the fill, faded in and out. The box
+   * itself never fades, for the reason recorded on `--_trough` — the rim stays
+   * at full strength and the shape never leaves the page. Zero at both ends of
+   * the cycle, so the seam where it wraps carries nothing to see.
+   */
+  [data-ui='skeleton'][data-part='root'][data-animation='pulse'][data-loading]::after,
+  [data-ui='skeleton'][data-animation='pulse'][data-loading] [data-part='line']::after {
+    animation-timing-function: ease-in-out;
+    background-color: var(--_trough);
+    opacity: 0;
+  }
+
+  /**
+   * A band crossing the box, and the geometry is the whole of it. The band is
+   * the middle 72 per cent of a layer the size of the box, and the layer
+   * travels from one box before it to one box past it, so the band comes in at
+   * one edge, crosses, and leaves at the other, with a rest between passes.
+   * That rest is what makes it read as something crossing the placeholder
+   * rather than as a gradient painted on it.
+   *
+   * The travel is symmetric about the box, so a right-to-left box runs the same
+   * travel backwards; `transform` and the gradient have no logical form.
+   */
+  [data-ui='skeleton'][data-part='root'][data-animation='shimmer'][data-loading]::after,
+  [data-ui='skeleton'][data-animation='shimmer'][data-loading] [data-part='line']::after {
+    animation-timing-function: linear;
+    background-image: linear-gradient(
+      90deg,
+      transparent 14%,
+      var(--_highlight) 50%,
+      transparent 86%
+    );
+  }
+
+  [data-ui='skeleton'][data-part='root'][data-animation='shimmer'][data-loading]:dir(rtl)::after,
+  [data-ui='skeleton'][data-animation='shimmer'][data-loading]:dir(rtl) [data-part='line']::after {
+    animation-direction: reverse;
+  }
+
+  /* Started only here: a reset under `reduce` is one attribute against the
+     four that select a layer, and lost, so the loop ran under reduced motion. */
+  @media (prefers-reduced-motion: no-preference) {
+    [data-ui='skeleton'][data-part='root'][data-animation='pulse'][data-loading]::after,
+    [data-ui='skeleton'][data-animation='pulse'][data-loading] [data-part='line']::after {
+      animation-name: slotted-skeleton-pulse;
+    }
+
+    [data-ui='skeleton'][data-part='root'][data-animation='shimmer'][data-loading]::after,
+    [data-ui='skeleton'][data-animation='shimmer'][data-loading] [data-part='line']::after {
+      animation-name: slotted-skeleton-sweep;
+    }
+  }
+
+  @keyframes slotted-skeleton-pulse {
+    50% {
+      opacity: 1;
+    }
+  }
+
+  @keyframes slotted-skeleton-sweep {
+    from {
+      transform: translateX(-100%);
+    }
+
+    to {
+      transform: translateX(100%);
+    }
+  }
+
+  /**
+   * The loop stops rather than hurries. A spinner reports through its motion
+   * and has nothing left to say once it is still; a placeholder reports
+   * through its shape, which does not move — so stillness costs this family
+   * nothing, and `docs/token-foundation.md` requires it of every infinite
+   * animation regardless. Still, the pulse layer is transparent and the band
+   * stands outside the box, so the reader sees the fill alone.
+   */
+  @media (prefers-reduced-motion: reduce) {
+    [data-ui='skeleton']::after,
+    [data-ui='skeleton'] [data-part='line']::after {
+      animation: none;
+    }
+  }
+
+  /**
+   * The theme remaps the fill to `Canvas` and the rim to `ButtonBorder`, so
+   * the box survives on its own. What does not survive is the gradient: a
+   * `background-image` is not replaced by the system palette, so a shimmer
+   * would go on painting a mixed colour over a forced one.
+   */
+  @media (forced-colors: active) {
+    [data-ui='skeleton'][data-part='root'][data-loading]::after,
+    [data-ui='skeleton'][data-part='text'][data-loading] [data-part='line']::after {
+      background-image: none;
+    }
+  }
+}

package/src/skeleton/skeleton.tokens.json

@@ -0,0 +1,29 @@
+[
+  "--slotted-avatar-size-lg",
+  "--slotted-avatar-size-md",
+  "--slotted-avatar-size-sm",
+  "--slotted-avatar-size-xl",
+  "--slotted-avatar-size-xs",
+  "--slotted-border-subtle",
+  "--slotted-border-width-thin",
+  "--slotted-disabled-background",
+  "--slotted-duration-loop-slow",
+  "--slotted-radius-full",
+  "--slotted-radius-md",
+  "--slotted-skeleton-block-size",
+  "--slotted-skeleton-border-color",
+  "--slotted-skeleton-border-width",
+  "--slotted-skeleton-fill",
+  "--slotted-skeleton-highlight-color",
+  "--slotted-skeleton-inline-size",
+  "--slotted-skeleton-last-line-size",
+  "--slotted-skeleton-line-size",
+  "--slotted-skeleton-min-block-size",
+  "--slotted-skeleton-phase",
+  "--slotted-skeleton-radius",
+  "--slotted-skeleton-row-size",
+  "--slotted-skeleton-size",
+  "--slotted-skeleton-trough-color",
+  "--slotted-surface-sunken",
+  "--slotted-text"
+]