Skip to content

feat(tokens): refactor context application for tokens #4224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: spectrum-two
Choose a base branch
from
Draft

feat(tokens): refactor context application for tokens #4224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .eslintrc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
"semi": ["warn", "always"],
"space-before-blocks": ["warn", "always"]
},
"ignorePatterns": ["!.storybook"],
"overrides": [
{
"files": ["*.json"],
Expand Down
31 changes: 27 additions & 4 deletions .github/QUICK-START.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,43 @@ Install the components you want along with their dependencies. Here's an example
yarn add -DW @spectrum-css/tokens @spectrum-css/typography @spectrum-css/page @spectrum-css/icon @spectrum-css/button
```

Spectrum CSS components utilize custom properties in order to change themes and scales. For these to apply, a couple of classes need to be added to the document’s `<html>` tag based on the [visual language](https://github.com/adobe/spectrum-css?tab=readme-ov-file#visual-language), [scale](https://github.com/adobe/spectrum-css?tab=readme-ov-file#scales), and [theme](https://github.com/adobe/spectrum-css?tab=readme-ov-file#themes-colorstops) you wish to use. For example, the following code snippet will display styling for the default Spectrum visual language using medium scale and light color theme:
Spectrum CSS components utilize custom properties in order to express our design language through a set of core tokens. We leverage the `@adobe/spectrum-tokens` data as a source of this design data and convert it into a set of CSS custom properties. This allows us to use the tokens in our components and to create a consistent design language across all of our components.

Some of these tokens have different values depending on the visual language or scale being used. The default values for all tokens are set to the default values for the light theme and medium scale.

To force the dark theme, you can add `color-scheme: dark` to your container element. Doing this will force the dark value to be used for all tokens that have one. This can be done at any level of the DOM and by leveraging the cascade, the color schemes can be nested or changed at any level. For example, if you want to force the dark theme for a specific component, you can add `color-scheme: dark` to that component's container element.

```html
<html class="spectrum spectrum--medium spectrum--light"></html>
<style>
:root {
/* Allow user preference to control the color scheme at first */
color-scheme: light dark;
}
</style>
<div class="container" style="color-scheme: dark">
<p>A dark themed container</p>
<div class="container" style="color-scheme: light">
<p>A light themed container</p>
</div>
</div>
```

The design language also includes a set of token values that represent different device sizes. At the moment, these values are only defined as "medium" and "large", with "medium" as the default which maps generally to a desktop or laptop screen. The "large" value is intended for smaller devices, such as phones and tablets. The default value for all tokens is set to the default value for the medium scale. To force the large scale, you can load the CSS overrides for the large scale:

```html
<link rel="stylesheet" href="node_modules/@spectrum-css/tokens/dist/css/mobile.css" />
```

This will override the default value for all tokens to the value for the large scale.

Use the `index.css` files in your project to include component and global styles ([background theme/colorstop](https://github.com/adobe/spectrum-css?tab=readme-ov-file#themes-colorstops), [platform scaling](https://github.com/adobe/spectrum-css?tab=readme-ov-file#scales), etc.) for the component. If you don't need all of the global styles, peek at the docs for [including assets](https://github.com/adobe/spectrum-css?tab=readme-ov-file#including-assets)). Use this file by including the stylesheet (plus stylesheets for dependencies) in the `<head>` tag:

```html
<head>
<!-- Include global tokens depedency first -->
<link
rel="stylesheet"
href="node_modules/@spectrum-css/tokens/dist/index.css"
href="node_modules/@spectrum-css/tokens/dist/css/index.css"
/>

<!-- Include index.css for the components you're using -->
Expand Down Expand Up @@ -51,7 +74,7 @@ To put it all together, your final html file will look like this:
<head>
<link
rel="stylesheet"
href="node_modules/@spectrum-css/tokens/dist/index.css"
href="node_modules/@spectrum-css/tokens/dist/css/index.css"
/>
<link
rel="stylesheet"
Expand Down
31 changes: 20 additions & 11 deletions .storybook/assets/base.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,33 +11,42 @@
* governing permissions and limitations under the License.
*/

body {
:root {
--spectrum-font-family: var(--spectrum-sans-font-family-stack);
--spectrum-font-style: var(--spectrum-default-font-style);
--spectrum-font-size: var(--spectrum-font-size-100);

/* Gradient that changes with the color theme. */
--spectrum-examples-gradient: linear-gradient(45deg, var(--spectrum-magenta-1500), var(--spectrum-blue-1500));

/* Gradients that do not change with the color theme, for use in static color backgrounds. */
--spectrum-examples-gradient-static-black: linear-gradient(45deg, rgb(255 241 246), rgb(238 245 255));
--spectrum-examples-gradient-static-white: linear-gradient(45deg, rgb(64 0 22), rgb(14 24 67));

color-scheme: light dark;
}

body {
margin: 0;

font-family: var(--spectrum-font-family);
font-size: var(--spectrum-font-size);
font-style: var(--spectrum-font-style);

color: var(--spectrum-neutral-content-color-default, rgb(34, 34, 34));
background-color: var(--spectrum-background-base-color, rgb(230, 230, 230));
}

.spectrum {
color: var(--spectrum-neutral-content-color-default);
background-color: var(--spectrum-background-base-color);
body,
.docs-story {
color: var(--spectrum-neutral-content-color-default, rgb(34, 34, 34));
background: var(--spectrum-background-base-color, rgb(230, 230, 230));
-webkit-tap-highlight-color: rgb(0, 0, 0, 0%);
}

.spectrum .spectrum-examples-static-black {
background: var(--spectrum-examples-gradient-static-black);
.spectrum-examples-static-black {
background: var(--spectrum-examples-gradient-static-black) !important;
}

.spectrum .spectrum-examples-static-white {
background: var(--spectrum-examples-gradient-static-white);
.spectrum-examples-static-white {
background: var(--spectrum-examples-gradient-static-white) !important;
}

/* Hide the SVG elements that only include references */
Expand Down
15 changes: 2 additions & 13 deletions .storybook/decorators/context.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,6 @@ export const withContextWrapper = makeDecorator({
// Start by attaching the appropriate tokens to the container
toggleStyles(document.body, "tokens", tokens, true);

// add the default classes to the body to ensure labels, headings, and borders are styled correctly
document.body.classList.add("spectrum", "spectrum--light", "spectrum--medium");

for (const container of fetchContainers(id, isDocs, isTesting)) {
// Check if the container is a testing wrapper to prevent applying colors around the testing grid
const isTestingWrapper = isTesting ? container.matches("body:has([data-testing-preview]),[data-testing-preview]") : false;
Expand All @@ -71,9 +68,6 @@ export const withContextWrapper = makeDecorator({
// If we can't determine the static key, we can't use the static color
if (!staticKey) hasStaticElement = false;

// Every container gets the spectrum class
container.classList.toggle("spectrum", true);

// Let the static color override the color if it's set
if (!isTestingWrapper && hasStaticElement && staticColorSettings[staticKey]?.color) {
color = staticColorSettings[staticKey].color;
Expand All @@ -85,13 +79,8 @@ export const withContextWrapper = makeDecorator({
color = "light";
}

for (let c of ["light", "dark"]) {
container.classList.toggle(`spectrum--${c}`, c === color);
}

for (const s of ["medium", "large"]) {
container.classList.toggle(`spectrum--${s}`, s === scale);
}
container.style.setProperty("color-scheme", color);
container.classList.toggle("spectrum--large", scale === "large");

if (!isTestingWrapper) {
if (hasStaticElement && staticKey && staticColorSettings[staticKey]) {
Expand Down
4 changes: 0 additions & 4 deletions .storybook/decorators/icon-sprites.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,6 @@ export const withIconSpriteSheet = makeDecorator({
name: "withIconSpriteSheet",
parameterName: "spritesheet",
wrapper: (StoryFn, context) => {
const {
loaded = {},
} = context;

useEffect(() => {
// Inject the sprite sheets into the document
let sprite = document.getElementById("spritesheets");
Expand Down
3 changes: 2 additions & 1 deletion .storybook/decorators/utilities.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ export const Container = ({
if (withBorder) {
borderStyles["padding-inline"] = "24px";
borderStyles["padding-block"] = "24px";
borderStyles["border"] = "1px solid rgba(var(--spectrum-gray-600-rgb), 20%)";
borderStyles["border"] = "1px solid color-mix(in srgb, var(--spectrum-gray-600) 20%, transparent)";
borderStyles["border-radius"] = "4px";
gap = 80;
}
Expand Down Expand Up @@ -158,6 +158,7 @@ export const Container = ({
"row-gap": "24px",
"align-items": heading && level > 1 ? "flex-start" : undefined,
"justify-content": direction === "column" ? "center" : "flex-start",
"background": level === 1 && !isDocs ? "var(--spectrum-background-base-color)" : undefined,
...borderStyles,
...wrapperStyles,
})}
Expand Down
9 changes: 4 additions & 5 deletions .storybook/foundations/drop-shadow/drop-shadow.stories.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import { html } from "lit";
import { classMap } from "lit/directives/class-map.js";
import { styleMap } from "lit/directives/style-map.js";

import "./index.css";

export default {
Expand Down Expand Up @@ -35,11 +37,8 @@ const DropShadowBackground = (
context,
) => html`
<div
class=${classMap({
[rootClass]: true,
"spectrum--light": color === "light",
"spectrum--dark": color === "dark",
})}
class=${classMap({ [rootClass]: true })}
style=${styleMap({ "color-scheme": color })}
>
${DropShadowSwatch(args, context)}
</div>
Expand Down
101 changes: 26 additions & 75 deletions .storybook/foundations/drop-shadow/index.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,106 +10,57 @@ OF ANY KIND, either express or implied. See the License for the specific languag
governing permissions and limitations under the License.
*/

/* stylelint-disable spectrum-tools/no-unknown-custom-properties */

.spectrum-Foundations-Example-DropShadow-swatch {
block-size: 150px;
inline-size: 150px;
background-color: var(--spectrum-gray-25);
border-radius: var(--spectrum-corner-radius-large-default);
border: transparent;
block-size: 150px;
inline-size: 150px;

/* matches dark mode design spec rgb(34, 34, 34) */
background-color: var(--spectrum-gray-25);
border-radius: var(--spectrum-corner-radius-large-default);
border: transparent;
}

.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch {
background-color: var(--spectrum-gray-75); /* matches dark mode design spec rgb(34, 34, 34) */
@media (prefers-color-scheme: dark) {
.spectrum-Foundations-Example-DropShadow-swatch {
background-color: var(--spectrum-gray-75);
}
}

.spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-box-shadow {
box-shadow:
var(--spectrum-drop-shadow-emphasized-default-x)
var(--spectrum-drop-shadow-emphasized-default-y)
var(--spectrum-drop-shadow-emphasized-default-blur)
var(--mod-drop-shadow-emphasized-default-color, var(--spectrum-drop-shadow-emphasized-default-color));
box-shadow: var(--spectrum-drop-shadow-emphasized-default-x) var(--spectrum-drop-shadow-emphasized-default-y) var(--spectrum-drop-shadow-emphasized-default-blur) var(--mod-drop-shadow-emphasized-default-color, var(--spectrum-drop-shadow-emphasized-default-color));
}

.spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-drop-shadow {
filter: drop-shadow(
var(--spectrum-drop-shadow-emphasized-default-x)
var(--spectrum-drop-shadow-emphasized-default-y)
calc(var(--spectrum-drop-shadow-emphasized-default-blur) / 2) /* adjust blur by half of box-shadow */
var(--mod-drop-shadow-emphasized-default-color, var(--spectrum-drop-shadow-emphasized-default-color))
);
}

.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-box-shadow,
.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-box-shadow,
.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-drop-shadow,
.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-drop-shadow {
/* adjustment because color tokens do not work properly on foundations pages */
--mod-drop-shadow-emphasized-default-color: var(--spectrum-drop-shadow-color-100);
filter: drop-shadow(var(--spectrum-drop-shadow-emphasized-default-x) var(--spectrum-drop-shadow-emphasized-default-y) calc(var(--spectrum-drop-shadow-emphasized-default-blur) / 2) /* adjust blur by half of box-shadow */ var(--mod-drop-shadow-emphasized-default-color, var(--spectrum-drop-shadow-emphasized-default-color)));
}

.spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-box-shadow {
box-shadow:
var(--spectrum-drop-shadow-emphasized-hover-x)
var(--spectrum-drop-shadow-emphasized-hover-y)
var(--spectrum-drop-shadow-emphasized-hover-blur)
var(--mod-drop-shadow-emphasized-hover-color, var(--spectrum-drop-shadow-emphasized-hover-color));
box-shadow: var(--spectrum-drop-shadow-emphasized-hover-x) var(--spectrum-drop-shadow-emphasized-hover-y) var(--spectrum-drop-shadow-emphasized-hover-blur) var(--mod-drop-shadow-emphasized-hover-color, var(--spectrum-drop-shadow-emphasized-hover-color));
}

.spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-drop-shadow {
filter: drop-shadow(
var(--spectrum-drop-shadow-emphasized-hover-x)
var(--spectrum-drop-shadow-emphasized-hover-y)
calc(var(--spectrum-drop-shadow-emphasized-hover-blur) / 2) /* adjust blur by half of box-shadow */
var(--mod-drop-shadow-emphasized-hover-color, var(--spectrum-drop-shadow-emphasized-hover-color))
);
}

.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-drop-shadow,
.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-drop-shadow,
.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-box-shadow,
.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-box-shadow {
/* adjustment because color tokens do not work properly on foundations pages */
--mod-drop-shadow-emphasized-hover-color: var(--spectrum-drop-shadow-color-200);
filter: drop-shadow(var(--spectrum-drop-shadow-emphasized-hover-x) var(--spectrum-drop-shadow-emphasized-hover-y) calc(var(--spectrum-drop-shadow-emphasized-hover-blur) / 2) /* adjust blur by half of box-shadow */ var(--mod-drop-shadow-emphasized-hover-color, var(--spectrum-drop-shadow-emphasized-hover-color)));
}

.spectrum-Foundations-Example-DropShadow-swatch--elevated-box-shadow {
box-shadow:
var(--spectrum-drop-shadow-elevated-x)
var(--spectrum-drop-shadow-elevated-y)
var(--spectrum-drop-shadow-elevated-blur)
var(--mod-drop-shadow-elevated-color, var(--spectrum-drop-shadow-elevated-color));
box-shadow: var(--spectrum-drop-shadow-elevated-x) var(--spectrum-drop-shadow-elevated-y) var(--spectrum-drop-shadow-elevated-blur) var(--mod-drop-shadow-elevated-color, var(--spectrum-drop-shadow-elevated-color));
}

.spectrum-Foundations-Example-DropShadow-swatch--elevated-drop-shadow {
filter: drop-shadow(
var(--spectrum-drop-shadow-elevated-x)
var(--spectrum-drop-shadow-elevated-y)
calc(var(--spectrum-drop-shadow-elevated-blur) / 2) /* adjust blur by half of box-shadow */
var(--mod-drop-shadow-elevated-color, var(--spectrum-drop-shadow-elevated-color))
);
}

.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--elevated-drop-shadow,
.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--elevated-drop-shadow,
.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--elevated-box-shadow,
.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--elevated-box-shadow {
/* adjustment because color tokens do not work properly on foundations pages */
--mod-drop-shadow-elevated-color: var(--spectrum-drop-shadow-color-200);
filter: drop-shadow(var(--spectrum-drop-shadow-elevated-x) var(--spectrum-drop-shadow-elevated-y) calc(var(--spectrum-drop-shadow-elevated-blur) / 2) /* adjust blur by half of box-shadow */ var(--mod-drop-shadow-elevated-color, var(--spectrum-drop-shadow-elevated-color)));
}

.spectrum-Foundations-Example-swatch-container {
background-color: var(--spectrum-gray-25);
block-size: 200px;
inline-size: 300px;
display: flex;
align-items: center;
justify-content: center;
background-color: var(--spectrum-gray-25);
block-size: 200px;
inline-size: 300px;
display: flex;
align-items: center;
justify-content: center;
}

.spectrum-Foundations-Example-variant-container {
background-color: var(--spectrum-gray-25);
display: flex;
flex-direction: row;
background-color: var(--spectrum-gray-25);
display: flex;
flex-direction: row;
}
11 changes: 1 addition & 10 deletions .storybook/manager.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,16 @@
import { addons } from "@storybook/manager-api";
import { create } from "@storybook/theming";
import { startCase } from "lodash";

import "./assets/index.css";

import logo from "./assets/logo.svg";
import pkg from "./package.json";

const root = document.body ?? document.documentElement;
if (root) root.classList.add("spectrum", "spectrum--light", "spectrum--medium");

addons.setConfig({
theme: create({
base: "light",

brandTitle: "Adobe | Spectrum CSS",
brandUrl: pkg.homepage ?? "https://opensource.adobe.com/spectrum-css",
brandUrl: "https://opensource.adobe.com/spectrum-css",
brandImage: logo,
brandTarget: "_self",

Expand Down Expand Up @@ -63,8 +58,4 @@ addons.setConfig({

// gridCellSize?: number;
}),
sidebar: {
showRoots: false,
renderLabel: ({ name, type }) => (type === 'story' ? name : startCase(name)) + " 📚",
},
});
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Start by including the base set of variables:

```css
/* Include tokens */
@import "node_modules/@spectrum-css/tokens/dist/index.css";
@import "node_modules/@spectrum-css/tokens/dist/css/index.css";

@import "node_modules/@spectrum-css/page/dist/index.css";
@import "node_modules/@spectrum-css/typography/dist/index.css";
Expand Down
Loading
Loading