Skip to content

[POC] Removing modifiers #4187

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 2 commits into
base: spectrum-two
Choose a base branch
from
Draft

[POC] Removing modifiers #4187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2163ef2
feat: remove modifiers from the API
castastrophe Aug 29, 2025
a8d29bd
feat(commons): remove need for commons package
castastrophe Sep 11, 2025
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
2 changes: 1 addition & 1 deletion .storybook/blocks/ColorPalette.jsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ export const ColorItem = ({ title, color, size = 60, values = [], noCheckerboard
<SwatchSet
className="swatch-set"
key={`${color}-${value}`}
style={{ "--mod-swatch-size": `${size}px` }}
style={{ "--spectrum-swatch-size": `${size}px` }}
>
<Body className="swatch-label" size="s">
{value}
Expand Down
29 changes: 15 additions & 14 deletions .storybook/blocks/PropertiesTable.jsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,12 @@ import React, { useContext } from 'react';
import { Table } from "./Layouts.jsx";
import { ThemeContainer } from "./ThemeContainer.jsx";
import { Body, Code, LinkableHeading } from "./Typography.jsx";
import styles from "@spectrum-css/bundle/dist/index.module.css";

/**
* Displays the modifiable custom properties for a component based on the metadata provided in the story.
* The story metadata object is imported from the "metadata.json" file in the component's directory.
*
* If the metadata object does not contain a "modifiers" array, this component will not render.
* If the metadata object does not contain a "component" array, this component will not render.
*
* Usage of this doc block within MDX template(s):
* <PropertiesTable />
Expand All @@ -23,26 +22,28 @@ export const PropertiesTable = () => {
const metadata = storyMeta?.csfFile?.meta?.parameters?.metadata ?? {};

if (!packageJson?.name) return;
if (!metadata?.modifiers || !metadata?.modifiers.length) return;
if (!metadata?.component || !metadata?.component.length) return;

return (
<ThemeContainer color="light" display="contents">
<LinkableHeading id="modifiable-properties" size="m">
<a aria-hidden="true" href="#modifiable-properties" tabIndex="-1" target="_self" onClick={() => {
context.channel.emit(NAVIGATE_URL, "#modifiable-properties");
}}></a>
Modifiable custom properties
<LinkableHeading id="custom-properties" size="m">
<a
aria-hidden="true"
href="#custom-properties"
tabIndex="-1"
target="_self"
onClick={() => {
context.channel.emit(NAVIGATE_URL, "#custom-properties");
}}
></a>
Custom properties
</LinkableHeading>
<Body>
These are empty CSS custom property hooks available in this component
that enable one-off customizations specific to a product implementation.
</Body>
<Table
headers={["Property"]}
rows={metadata?.modifiers.map((propertyName) => [
rows={metadata?.component.map((propertyName) => [
<Code backgroundColor={"transparent"} size="s">
{propertyName}
</Code>
</Code>,
])}
/>
</ThemeContainer>
Expand Down
83 changes: 27 additions & 56 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,77 @@ 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;
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) */
background-color: var(--spectrum-gray-75); /* matches dark mode design spec rgb(34, 34, 34) */
}

.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(--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))
);
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(--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);
/* adjustment because color tokens do not work properly on foundations pages */
--spectrum-drop-shadow-emphasized-default-color: var(--spectrum-drop-shadow-color-100);
}

.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(--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))
);
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(--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);
/* adjustment because color tokens do not work properly on foundations pages */
--spectrum-drop-shadow-emphasized-hover-color: var(--spectrum-drop-shadow-color-200);
}

.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(--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))
);
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(--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);
/* adjustment because color tokens do not work properly on foundations pages */
--spectrum-drop-shadow-elevated-color: var(--spectrum-drop-shadow-color-200);
}

.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;
}
2 changes: 1 addition & 1 deletion .storybook/guides/releasing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { Meta, Title } from "@storybook/blocks";

This project versions components independently, meaning each component has its own version number, updated independently of other components. We follow [semantic versioning](https://semver.org/) and as such, each release is versioned according to the following rules:

- **Major**: Breaking changes such as API changes, the removal of features, or changes to `--mod` custom properties
- **Major**: Breaking changes such as API changes or the removal of features
- **Minor**: New features or enhancements
- **Patch**: Bug fixes or minor improvements

Expand Down
12 changes: 4 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<h1 align="center">Spectrum CSS</h1>
<h3 align="center">A CSS-implementation of the Spectrum design language</h3>

<img src=".storybook/assets/images/spectrum-css_illustration_desktop.png">
<img src=".storybook/assets/images/spectrum-css_illustration_desktop.png" alt="Spectrum CSS illustration" />

## Features

Expand All @@ -16,7 +16,7 @@
- 🧪 **Rigorously tested**: These individually-versioned components have been vetted to be accessible and inclusive of global audiences.
- 📱 **Multi-platform support**: We support [evergreen browsers](https://github.com/adobe/spectrum-css?tab=readme-ov-file#browser-support) for scalability and flexibility.

&nbsp;&nbsp;&nbsp;&nbsp; [<img src="https://img.shields.io/badge/Get%20started-F0F0F0?style=for-the-badge&logo=adobe&logoColor=%23FF0000"/>](https://opensource.adobe.com/spectrum-css/get-started.html) &nbsp; [<img src="https://img.shields.io/badge/Storybook-F0F0F0?style=for-the-badge&logo=storybook&logoColor=%23FF4785"/>](https://opensource.adobe.com/spectrum-css/)
&nbsp;&nbsp;&nbsp;&nbsp; [<img src="https://img.shields.io/badge/Get%20started-F0F0F0?style=for-the-badge&logo=adobe&logoColor=%23FF0000" alt="Get started" />](https://opensource.adobe.com/spectrum-css/get-started.html) &nbsp; [<img src="https://img.shields.io/badge/Storybook-F0F0F0?style=for-the-badge&logo=storybook&logoColor=%23FF4785" alt="Storybook" />](https://opensource.adobe.com/spectrum-css/)

## Using Spectrum CSS

Expand Down Expand Up @@ -44,13 +44,13 @@ yarn add -DW @spectrum-css/tokens @spectrum-css/typography @spectrum-css/page @s

Installed components will be available in the `node_modules/@spectrum-css/` folder of your project.

All components in this library have a peer dependency on [`@spectrum-css/tokens`](tokens), which is a local package that serves up the [Spectrum design tokens](https://github.com/adobe/spectrum-tokens) as CSS custom properties (via [Style dictionary](https://amzn.github.io/style-dictionary/#/)). These custom properties are leveraged in all components to create a cohesive visual language and to allow for easy theming. If you choose not to use the provided `@spectrum-css/tokens` package, you must define your own custom properties or your components will render with a significant number of missing styles. When overriding certain styles is necessary, modifying styles is supported through the use of component-specific `--mod` prefixed properties. [More on this below](https://github.com/adobe/spectrum-css?tab=readme-ov-file#modifying-components).
All components in this library have a peer dependency on [`@spectrum-css/tokens`](tokens), which is a local package that serves up the [Spectrum design tokens](https://github.com/adobe/spectrum-tokens) as CSS custom properties (via [Style dictionary](https://amzn.github.io/style-dictionary/#/)). These custom properties are leveraged in all components to create a cohesive visual language and to allow for easy theming. If you choose not to use the provided `@spectrum-css/tokens` package, you must define your own custom properties or your components will render with a significant number of missing styles.

### Using components in your project

Spectrum CSS components have build output that is designed to be used in a variety of ways:

- `index.css` - _Preferred and most commonly used to incorporate Spectrum CSS into a project_. This file includes the component's styles and variable definitions. In this version, token-driven CSS properties<sup>[1](#token-footnote)</sup> are mapped to empty `--mod` prefixed variables (for customization) with a fallback to variables prefixed with `--spectrum` (sourced from the design tokens).
- `index.css` - _Preferred and most commonly used to incorporate Spectrum CSS into a project_. This file includes the component's styles and variable definitions. In this version, component-specific custom properties<sup>[1](#token-footnote)</sup> are mapped to variables sourced from the design tokens.

<sup><a name="token-footnote">1</a></sup>: Token-driven CSS properties are properties whose values are mapped to a value in the `@spectrum-css/tokens` package. These values represent design-language and are meant to be used across platforms. In contrast, properties specific to web-based implementations will not have a token value assigned, so not all CSS properties will use custom properties.

Expand Down Expand Up @@ -104,10 +104,6 @@ Put together, we would define the context for our application in the following w

Because CSS custom properties honor the cascading nature of CSS, you can infinitely nest different contexts. For example, you could have a `.spectrum--dark` context inside of a `.spectrum--light` context, and components will honor the innermost context.

### Modifying components

You can override variables and modify Spectrum CSS' look and feel by re-defining the custom properties in context. Look for the **Custom Property API** section in each component to determine which custom properties you can override. See [Action Button for a complete example](https://opensource.adobe.com/spectrum-css/actionbutton.html#custompropertiesapi).

### Importing UI icons

Some components require certain "UI icons" to render. These icons are released within the [`@spectrum-css/ui-icons`](https://www.npmjs.com/package/@spectrum-css/ui-icons) package and are used by components like `@spectrum-css/icon` and `@spectrum-css/actionbutton`.
Expand Down
Loading
Loading