@czi-sds/mcp 0.20.1 → 0.21.0

package/data/component-docs/Tag.md

@@ -12,21 +12,47 @@ The component's source code in the SDS codebase can be found [here](https://gith
 import { Tag } from "@czi-sds/components";
 ```
 
+> **Coming from the Tag before SDS 25?** Its API changed: `sdsStyle` is now `"solid"` or `"outline"`, sizes are `"small"` and `"medium"`, and `sdsType` and `hover` are gone. The previous component still ships as TagLegacy, and the table under "Migrating from TagLegacy" maps each old prop to its new one.
+
 ## Code examples
 
 ### **Default Tag**
 
-A tag with nothing but a label, next to the same tag asking for the rounded shape the design guidance prefers.
+A tag with nothing but a label: neutral, solid and medium.
 
 **Example: DefaultTag**
 
 ```tsx
-// A label is all a Tag needs. Everything else has a default: the neutral grey
-// intent, the small size, and the square shape.
+// A label is all a Tag needs. Everything else has a default: the neutral intent,
+// the solid style and the medium size. A tag is pill-shaped; only an icon-only
+// tag is square.
+
+import { Tag } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <Tag label="Science Design System" />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Styles and intents
+
+The seven intents, drawn solid and then outlined. A tag left without a color is neutral.
+
+**Example: TagStylesAndIntents**
+
+```tsx
+// color carries the tag's intent. Seven are available, and neutral is what a tag
+// falls back to when the prop is left out.
 //
-// Note that the component defaults to square while the design guidance above
-// treats rounded as the shape to reach for, so a tag that should match the rest
-// of the system asks for it: sdsStyle="rounded".
+// sdsStyle picks how that intent is drawn: solid fills the tag with the intent
+// color and sets the label white, outline tints the fill and draws the label,
+// the icons and a 1px border in the intent color.
 
 import {
   Tag,
@@ -34,9 +60,23 @@ import {
   getSemanticColors,
   getSpaces,
   type CommonThemeProps,
+  type SdsTagIntent,
+  type SdsTagStyle,
 } from "@czi-sds/components";
 import styled from "@emotion/styled";
 
+const INTENTS: SdsTagIntent[] = [
+  "accent",
+  "beta",
+  "info",
+  "negative",
+  "neutral",
+  "notice",
+  "positive",
+];
+
+const STYLES: SdsTagStyle[] = ["solid", "outline"];
+
 const Stack = styled.div<CommonThemeProps>`
   ${(props) => {
     const spaces = getSpaces(props);
@@ -49,14 +89,14 @@ const Stack = styled.div<CommonThemeProps>`
   }}
 `;
 
-const Group = styled.div<CommonThemeProps>`
+const Row = styled.div<CommonThemeProps>`
   ${(props) => {
     const spaces = getSpaces(props);
 
     return `
-      align-items: center;
       display: flex;
-      gap: ${spaces?.m}px;
+      flex-wrap: wrap;
+      gap: ${spaces?.s}px;
     `;
   }}
 `;
@@ -66,11 +106,11 @@ const Caption = styled.p<CommonThemeProps>`
 
   ${(props) => {
     const semanticColors = getSemanticColors(props);
+    const spaces = getSpaces(props);
 
     return `
       color: ${semanticColors?.base?.textSecondary};
-      margin: 0;
-      min-width: 110px;
+      margin: 0 0 ${spaces?.xxs}px;
     `;
   }}
 `;
@@ -79,15 +119,21 @@ function App() {
   return (
     <div className="app">
       <Stack>
-        <Group>
-          <Caption>Square</Caption>
-          <Tag label="Science Design System" />
-        </Group>
-
-        <Group>
-          <Caption>Rounded</Caption>
-          <Tag label="Science Design System" sdsStyle="rounded" />
-        </Group>
+        {STYLES.map((sdsStyle) => (
+          <div key={sdsStyle}>
+            <Caption>{sdsStyle}</Caption>
+            <Row>
+              {INTENTS.map((intent) => (
+                <Tag
+                  color={intent}
+                  key={intent}
+                  label={intent}
+                  sdsStyle={sdsStyle}
+                />
+              ))}
+            </Row>
+          </div>
+        ))}
       </Stack>
     </div>
   );
@@ -96,19 +142,16 @@ function App() {
 export default App;
 ```
 
-### Intents
+### Sizes
 
-The six intents, drawn as primary and then as secondary. A tag left without a color is neutral.
+The medium and small sizes, each with a label, a label and an icon, and the icon alone.
 
-**Example: TagIntents**
+**Example: TagSizes**
 
 ```tsx
-// color carries the tag's intent. Six names are available, and neutral is what a
-// tag falls back to when the prop is left out.
-//
-// sdsType picks how that intent is drawn: primary fills the tag with the intent
-// color and sets the label white, secondary tints the fill and keeps the label in
-// the intent color behind a matching border.
+// size is medium unless it is set to small. A medium tag is 24px tall with a 13px
+// label and 12px icons; a small one is 20px tall with a 10px label and 10px
+// icons. Small suits a dense row, like a navigation bar or a tab's label.
 
 import {
   Tag,
@@ -116,18 +159,9 @@ import {
   getSemanticColors,
   getSpaces,
   type CommonThemeProps,
-  type SdsTagColorType,
 } from "@czi-sds/components";
 import styled from "@emotion/styled";
-
-const INTENTS: Extract<SdsTagColorType, string>[] = [
-  "info",
-  "positive",
-  "notice",
-  "negative",
-  "neutral",
-  "beta",
-];
+import { StackIcon } from "@phosphor-icons/react";
 
 const Stack = styled.div<CommonThemeProps>`
   ${(props) => {
@@ -141,14 +175,14 @@ const Stack = styled.div<CommonThemeProps>`
   }}
 `;
 
-const Row = styled.div<CommonThemeProps>`
+const Group = styled.div<CommonThemeProps>`
   ${(props) => {
     const spaces = getSpaces(props);
 
     return `
+      align-items: center;
       display: flex;
-      flex-wrap: wrap;
-      gap: ${spaces?.s}px;
+      gap: ${spaces?.m}px;
     `;
   }}
 `;
@@ -158,11 +192,11 @@ const Caption = styled.p<CommonThemeProps>`
 
   ${(props) => {
     const semanticColors = getSemanticColors(props);
-    const spaces = getSpaces(props);
 
     return `
       color: ${semanticColors?.base?.textSecondary};
-      margin: 0 0 ${spaces?.xxs}px;
+      margin: 0;
+      min-width: 80px;
     `;
   }}
 `;
@@ -171,34 +205,74 @@ function App() {
   return (
     <div className="app">
       <Stack>
-        <div>
-          <Caption>Primary</Caption>
-          <Row>
-            {INTENTS.map((intent) => (
-              <Tag
-                color={intent}
-                key={intent}
-                label={intent}
-                sdsStyle="rounded"
-              />
-            ))}
-          </Row>
-        </div>
+        <Group>
+          <Caption>medium</Caption>
+          <Tag color="accent" label="Annotated" />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            label="Annotated"
+          />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            iconOnly
+            label="Annotated"
+          />
+          <Tag color="accent" label="Annotated" sdsStyle="outline" />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            label="Annotated"
+            sdsStyle="outline"
+          />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            iconOnly
+            label="Annotated"
+            sdsStyle="outline"
+          />
+        </Group>
 
-        <div>
-          <Caption>Secondary</Caption>
-          <Row>
-            {INTENTS.map((intent) => (
-              <Tag
-                color={intent}
-                key={intent}
-                label={intent}
-                sdsStyle="rounded"
-                sdsType="secondary"
-              />
-            ))}
-          </Row>
-        </div>
+        <Group>
+          <Caption>small</Caption>
+          <Tag color="accent" label="Annotated" size="small" />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            label="Annotated"
+            size="small"
+          />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            iconOnly
+            label="Annotated"
+            size="small"
+          />
+          <Tag
+            color="accent"
+            label="Annotated"
+            size="small"
+            sdsStyle="outline"
+          />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            label="Annotated"
+            size="small"
+            sdsStyle="outline"
+          />
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            iconOnly
+            label="Annotated"
+            size="small"
+            sdsStyle="outline"
+          />
+        </Group>
       </Stack>
     </div>
   );
@@ -209,28 +283,29 @@ export default App;
 
 ### Tag + Icon
 
-A large tag, which has to carry an icon, beside a small one. Each uses an Icon whose own size matches the size the tag will draw it at.
+A leading icon from Phosphor or from `@czi-sds/icons`, and an icon-only tag inside the Tooltip that shows its label.
 
-**Example: TagIcon**
+**Example: TagIcons**
 
 ```tsx
-// An icon goes on the leading edge of a tag, and the large size requires one:
-// TypeScript rejects sdsSize="l" without it.
+// An icon goes on the leading edge of a tag. The tag draws it at its own size,
+// 12px in a medium tag and 10px in a small one, and in its own color, so pass a
+// bare icon: one from Phosphor, or one from @czi-sds/icons for the icons SDS
+// draws itself.
 //
-// The tag draws whatever icon it is given at a fixed size: 12px in a small tag,
-// 24px in a large one. Match the Icon's own sdsSize to that so the artwork is
-// drawn at the size it was made for: s or xs for a small tag, l for a large one.
-// Not every icon exists at both sizes: Virus below is large-only, so asking for it
-// at a small size renders nothing and logs an error.
+// iconOnly hides the label and squares the tag off. The label still names the
+// tag for screen readers, but sighted users only see the icon, so an icon-only
+// tag belongs in a Tooltip that shows the label.
 
-import { Icon, Tag } from "@czi-sds/components";
-import styled from "@emotion/styled";
 import {
-  fontBodyXs,
-  getSemanticColors,
+  Tag,
+  Tooltip,
   getSpaces,
   type CommonThemeProps,
 } from "@czi-sds/components";
+import { StackIcon } from "@phosphor-icons/react";
+import { CheckCircleIcon } from "@phosphor-icons/react";
+import styled from "@emotion/styled";
 
 const Row = styled.div<CommonThemeProps>`
   ${(props) => {
@@ -245,16 +320,67 @@ const Row = styled.div<CommonThemeProps>`
   }}
 `;
 
-const Caption = styled.p<CommonThemeProps>`
-  ${fontBodyXs}
+function App() {
+  return (
+    <div className="app">
+      <Row>
+        <Tag
+          color="accent"
+          icon={<StackIcon weight="fill" />}
+          label="Generated"
+        />
+
+        <Tag
+          color="positive"
+          icon={<CheckCircleIcon />}
+          label="Verified"
+          sdsStyle="outline"
+        />
+
+        <Tooltip placement="top" title="Generated">
+          <Tag
+            color="accent"
+            icon={<StackIcon weight="fill" />}
+            iconOnly
+            label="Generated"
+          />
+        </Tooltip>
+      </Row>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Tag as a link
 
+A tag with an `href` is a link. The arrow that says so is optional.
+
+**Example: TagAsLink**
+
+```tsx
+// href turns a tag into a link: it renders as an <a>, takes a tab stop, and
+// follows its href on click and on Enter. showLinkIcon adds an arrow after the
+// label to say the tag leads somewhere. The arrow is optional; a tag with an
+// href is a link either way.
+//
+// target="_blank" also sets rel="noopener noreferrer". For client-side routing,
+// pass your router's link component as component and the tag renders that
+// instead of a plain anchor.
+
+import { Tag, getSpaces, type CommonThemeProps } from "@czi-sds/components";
+import styled from "@emotion/styled";
+
+const Row = styled.div<CommonThemeProps>`
   ${(props) => {
-    const semanticColors = getSemanticColors(props);
     const spaces = getSpaces(props);
 
     return `
-      color: ${semanticColors?.base?.textSecondary};
-      margin: 0 0 ${spaces?.xxs}px;
+      align-items: center;
+      display: flex;
+      flex-wrap: wrap;
+      gap: ${spaces?.m}px;
     `;
   }}
 `;
@@ -262,23 +388,29 @@ const Caption = styled.p<CommonThemeProps>`
 function App() {
   return (
     <div className="app">
-      <Caption>
-        A large tag with a large icon, and a small tag with a small one
-      </Caption>
       <Row>
         <Tag
-          color="negative"
-          icon={<Icon sdsIcon="Virus" sdsSize="l" />}
-          label="Virus"
-          sdsSize="l"
-          sdsStyle="rounded"
+          color="info"
+          href="https://sds.czi.design"
+          label="SDS website"
+          showLinkIcon
+          target="_blank"
+        />
+
+        <Tag
+          color="info"
+          href="https://sds.czi.design"
+          label="SDS website"
+          sdsStyle="outline"
+          showLinkIcon
+          target="_blank"
         />
 
         <Tag
-          color="negative"
-          icon={<Icon sdsIcon="Bacteria" sdsSize="s" />}
-          label="Bacteria"
-          sdsStyle="rounded"
+          color="info"
+          href="https://sds.czi.design"
+          label="Without the arrow"
+          target="_blank"
         />
       </Row>
     </div>
@@ -288,29 +420,29 @@ function App() {
 export default App;
 ```
 
-### Tag with custom colors
+### Clickable, static and disabled tags
 
-Colors given as a tuple, for a tag the intents do not cover. The two-value form leaves the icon white, so a tag with an icon wants all three.
+A tag with an `onClick` behaves as a button for both the pointer and the keyboard. A tag without one stays a static label, and `disabled` turns a clickable tag off.
 
-**Example: TagWithCustomColors**
+**Example: InteractiveTag**
 
 ```tsx
-// color also takes a tuple of CSS colors for a tag the intents do not cover:
-// [label, background] or [label, background, icon].
+// A tag with an onClick becomes a button: it takes a tab stop, answers Enter and
+// Space, reports its label as its name, and darkens under the pointer. A tag with
+// neither an onClick nor an href is static: no role, no tab stop and no hover
+// state, so it reads as a label rather than a control.
 //
-// The two-value form does not touch the icon, which stays white and disappears on
-// a light background (the first tag below). A tag with an icon wants the
-// three-value form, and the contrast of whatever colors you pick is on you, since
-// SDS only guarantees it for its own intents.
+// disabled greys a clickable tag out and takes it out of the tab order.
 
-import { Icon, Tag } from "@czi-sds/components";
-import styled from "@emotion/styled";
 import {
+  Tag,
   fontBodyXs,
   getSemanticColors,
   getSpaces,
   type CommonThemeProps,
 } from "@czi-sds/components";
+import styled from "@emotion/styled";
+import { useState } from "react";
 
 const Stack = styled.div<CommonThemeProps>`
   ${(props) => {
@@ -345,45 +477,58 @@ const Caption = styled.p<CommonThemeProps>`
     return `
       color: ${semanticColors?.base?.textSecondary};
       margin: 0;
-      min-width: 180px;
+      min-width: 150px;
+    `;
+  }}
+`;
+
+const Readout = styled.p<CommonThemeProps>`
+  ${fontBodyXs}
+
+  ${(props) => {
+    const semanticColors = getSemanticColors(props);
+
+    return `
+      color: ${semanticColors?.base?.textSecondary};
+      margin: 0;
     `;
   }}
 `;
 
 function App() {
+  const [clicks, setClicks] = useState(0);
+
   return (
     <div className="app">
       <Stack>
         <Group>
-          <Caption>[label, background]</Caption>
+          <Caption>Clickable</Caption>
           <Tag
-            color={["#3b2f00", "#ffe6a0"]}
-            icon={<Icon sdsIcon="Star" sdsSize="l" />}
-            label="Icon left white"
-            sdsSize="l"
-            sdsStyle="rounded"
+            color="info"
+            label="Filter by species"
+            onClick={() => setClicks((count) => count + 1)}
           />
         </Group>
 
         <Group>
-          <Caption>[label, background, icon]</Caption>
-          <Tag
-            color={["#3b2f00", "#ffe6a0", "#b26f00"]}
-            icon={<Icon sdsIcon="Star" sdsSize="l" />}
-            label="Icon colored too"
-            sdsSize="l"
-            sdsStyle="rounded"
-          />
+          <Caption>Static</Caption>
+          <Tag label="Read-only label" />
         </Group>
 
         <Group>
-          <Caption>No icon, two values</Caption>
+          <Caption>Disabled</Caption>
           <Tag
-            color={["#3b2f00", "#ffe6a0"]}
-            label="Label and background"
-            sdsStyle="rounded"
+            color="info"
+            disabled
+            label="Filter by tissue"
+            onClick={() => setClicks((count) => count + 1)}
           />
         </Group>
+
+        <Readout>
+          The clickable tag has been activated {clicks}{" "}
+          {clicks === 1 ? "time" : "times"}, by pointer or by keyboard.
+        </Readout>
       </Stack>
     </div>
   );
@@ -392,21 +537,20 @@ function App() {
 export default App;
 ```
 
-### Clickable and static tags
+### Tag with custom colors
 
-A tag with an `onClick` behaves as a button for both the pointer and the keyboard. A tag that only labels something uses `hover={false}` so it stops looking clickable.
+Colors given as a tuple, for a tag the intents do not cover.
 
-**Example: InteractiveTag**
+**Example: TagWithCustomColors**
 
 ```tsx
-// A tag with an onClick becomes a button: it takes a tab stop, answers Enter and
-// Space, and reports its label as its name. Use it for a tag that filters or
-// navigates, not for one that only labels something.
+// color also takes a tuple of CSS colors for a tag the intents do not cover:
+// [label, background] or [label, background, icon]. The icon takes the label
+// color when the third value is left out, and an outline tag draws its border
+// from the label color too.
 //
-// Every tag darkens under the pointer and shows a pointer cursor by default,
-// including one that does nothing. hover={false} turns that off, and with it all
-// pointer events, so a static tag stops looking clickable, but it also stops
-// answering the mouse and stops triggering a Tooltip wrapped around it.
+// The contrast of whatever colors you pick is on you, since SDS only guarantees
+// it for its own intents.
 
 import {
   Tag,
@@ -416,7 +560,7 @@ import {
   type CommonThemeProps,
 } from "@czi-sds/components";
 import styled from "@emotion/styled";
-import { useState } from "react";
+import { StarIcon } from "@phosphor-icons/react";
 
 const Stack = styled.div<CommonThemeProps>`
   ${(props) => {
@@ -451,49 +595,41 @@ const Caption = styled.p<CommonThemeProps>`
     return `
       color: ${semanticColors?.base?.textSecondary};
       margin: 0;
-      min-width: 150px;
-    `;
-  }}
-`;
-
-const Readout = styled.p<CommonThemeProps>`
-  ${fontBodyXs}
-
-  ${(props) => {
-    const semanticColors = getSemanticColors(props);
-
-    return `
-      color: ${semanticColors?.base?.textSecondary};
-      margin: 0;
+      min-width: 180px;
     `;
   }}
 `;
 
 function App() {
-  const [clicks, setClicks] = useState(0);
-
   return (
     <div className="app">
       <Stack>
         <Group>
-          <Caption>Clickable</Caption>
+          <Caption>[label, background]</Caption>
           <Tag
-            color="info"
-            label="Filter by species"
-            onClick={() => setClicks((count) => count + 1)}
-            sdsStyle="rounded"
+            color={["#3b2f00", "#ffe6a0"]}
+            icon={<StarIcon />}
+            label="Icon takes the label color"
           />
         </Group>
 
         <Group>
-          <Caption>Static</Caption>
-          <Tag hover={false} label="Read-only label" sdsStyle="rounded" />
+          <Caption>[label, background, icon]</Caption>
+          <Tag
+            color={["#3b2f00", "#ffe6a0", "#b26f00"]}
+            icon={<StarIcon />}
+            label="Icon colored on its own"
+          />
         </Group>
 
-        <Readout>
-          The clickable tag has been activated {clicks}{" "}
-          {clicks === 1 ? "time" : "times"}, by pointer or by keyboard.
-        </Readout>
+        <Group>
+          <Caption>Outline</Caption>
+          <Tag
+            color={["#3b2f00", "#fff8e0"]}
+            label="Border from the label"
+            sdsStyle="outline"
+          />
+        </Group>
       </Stack>
     </div>
   );
@@ -509,13 +645,10 @@ What a long label does in a narrow container, and the Tooltip that keeps the tru
 **Example: TagWithLongLabel**
 
 ```tsx
-// A tag never wraps: it stretches to its label and then, in a container too narrow
-// for it, cuts the label off with an ellipsis. The text that is cut is not
+// A tag never wraps: it stretches to its label and then, in a container too
+// narrow for it, cuts the label off with an ellipsis. The text that is cut is not
 // available anywhere else, so a tag that can hold a long value belongs in a
 // Tooltip that carries the whole thing.
-//
-// The tooltip only works because the tag still receives pointer events. Adding
-// hover={false} to quiet the hover styling would silence the tooltip with it.
 
 import {
   Tag,
@@ -544,10 +677,11 @@ const Stack = styled.div<CommonThemeProps>`
 const NarrowColumn = styled.div<CommonThemeProps>`
   ${(props) => {
     const semanticColors = getSemanticColors(props);
+    const spaces = getSpaces(props);
 
     return `
       border: 1px dashed ${semanticColors?.base?.divider};
-      padding: 4px;
+      padding: ${spaces?.xxs}px;
       width: 160px;
     `;
   }}
@@ -573,7 +707,7 @@ function App() {
       <Stack>
         <div>
           <Caption>Room for the whole label</Caption>
-          <Tag label={LABEL} sdsStyle="rounded" />
+          <Tag label={LABEL} />
         </div>
 
         <div>
@@ -582,7 +716,7 @@ function App() {
           </Caption>
           <NarrowColumn>
             <Tooltip placement="top" title={LABEL}>
-              <Tag label={LABEL} sdsStyle="rounded" />
+              <Tag label={LABEL} />
             </Tooltip>
           </NarrowColumn>
         </div>
@@ -596,21 +730,21 @@ export default App;
 
 ## SDS vs MUI
 
-SDS Tag wraps MUI's Chip and replaces its palette, sizing and shape with SDS ones. SDS also splits the Chip's two jobs in two: Tag labels something, and TagFilter is the tag that can be removed. The differences from MUI are these:
+SDS Tag wraps MUI's Chip and replaces its palette, sizing and shape with SDS ones. SDS also splits the Chip's two jobs in two: Tag labels something, and Chip is the one that can be removed. The differences from MUI are these:
 
-- `sdsStyle`: `"square"` or `"rounded"`. The component defaults to `"square"`, while the design guidance above treats rounded as the shape to reach for, so a tag that should match the rest of the system asks for it explicitly.
+- `sdsStyle`: `"solid"` (default) fills the tag with the intent color and sets the label white; `"outline"` tints the fill and draws the label, the icons and a 1px border in the intent color. It replaces MUI's `variant`, which Tag does not take.
 
-- `sdsType`: `"primary"` (default) fills the tag with the intent color and sets the label white; `"secondary"` tints the fill, keeps the label in the intent color and draws a 1px border in it.
+- `size`: MUI's own prop, but with SDS measurements. `"medium"` (default) is 24px tall with a 13px label and 12px icons, `"small"` is 20px tall with a 10px label and 10px icons.
 
-- `sdsSize`: `"s"` (default) or `"l"`, which is the pair of sizes the design carries rather than MUI's `"small"` and `"medium"`. A large tag must have an icon: TypeScript rejects `sdsSize="l"` without one.
+- `color`: an SDS intent rather than one of MUI's palette names. Seven intents are available, `"accent"` among them, and a tag without the prop is neutral. It also takes a tuple of CSS colors for cases the intents do not cover.
 
-- `color`: an SDS intent rather than one of MUI's palette names, since SDS hands MUI a fixed color of its own and uses this prop for the fill, the label and the icon. Six intents are available and a tag without the prop is neutral. It also takes a tuple of CSS colors for cases the intents do not cover.
+- **The shape follows the content:** a tag with a label is pill-shaped, and an icon-only tag (`iconOnly`) is square with 4px corners. There is no prop for it.
 
-- `hover`: on by default, which draws the hover and pressed states and a pointer cursor on every tag, whether or not anything happens when it is clicked. Setting it to `false` removes those states by taking the tag out of pointer events entirely, which also stops a Tooltip wrapped around it from opening.
+- **Links:** `href` renders the tag as an `<a>`, which MUI's Chip only does when it is also handed `component="a"` and `clickable`. Passing `component` still works, so a router's link component can take the anchor's place. `showLinkIcon` adds Phosphor's ArrowUpRight after the label.
 
-- **Sizing and variant props do nothing:** MUI's `size` and `variant` set their classes but SDS pins the height, padding, fill and border, so a tag looks the same either way. MUI's `clickable` does have an effect, and not a useful one: it makes the tag a tab stop that does nothing. Pass `onClick` instead.
+- **Interactive styling follows behavior:** the hover and pressed states, the pointer cursor and the focus ring appear only on a tag with an `onClick` or an `href`, or one set `clickable`. A tag that only labels something has none of them.
 
-- **onDelete works, but off-brand:** a Tag given `onDelete` does become deletable, drawing MUI's filled-circle Cancel icon rather than the SDS X. Reach for TagFilter when a tag needs to come off.
+- **onDelete works, but Chip is the removable tag:** a Tag given `onDelete` becomes deletable and draws MUI's Cancel icon at the tag's icon size. Reach for Chip when a tag needs to come off.
 
 ## MUI Documentation
 
@@ -618,30 +752,53 @@ Documentation for the underlying MUI component can be found [here](https://mui.c
 
 ## Behavior and accessibility
 
-- A plain tag is a div holding its label, with no role and no tab stop, and is read as the text it shows. Giving it an `onClick` turns it into a button: it takes a tab stop, answers Enter and Space, and takes its accessible name from the label.
+- A plain tag is a div holding its label, with no role and no tab stop, and is read as the text it shows. Giving it an `onClick` turns it into a button: it takes a tab stop, answers Enter and Space, and takes its accessible name from the label. Giving it an `href` turns it into a link instead.
 
-- Because `hover` is on by default, a tag that only labels something still darkens under the pointer and shows a pointer cursor, which reads as clickable. `hover={false}` settles that, at the cost of all pointer events, so do not combine it with `onClick`, which would leave the tag reachable by keyboard but dead to the mouse.
+- `disabled` greys a tag out. On a clickable tag or a link it also sets `aria-disabled` and takes the tag out of the tab order; on a static tag it changes nothing but the colors, so say in the label why the thing it describes is unavailable.
 
 - Nothing about the intent reaches assistive technology: `color` is color only, so a negative tag needs a label that says what is wrong rather than relying on red.
 
+- An icon-only tag keeps its label as its accessible name, hidden from view but read by screen readers. Sighted users see only the icon, so wrap the tag in a Tooltip that shows the label.
+
+- The link arrow is decorative and hidden from screen readers. A link that opens in a new tab with `target="_blank"` should say so in its label or in text beside it.
+
 - A tag never wraps. It stretches to fit its label and then, in a container too narrow, cuts the label off with an ellipsis, leaving the rest of the text nowhere else to be read. A tag that can hold a long value belongs in a Tooltip carrying the whole string.
 
-- Icons are drawn at a fixed size (12px in a small tag, 24px in a large one) whatever size the Icon itself asks for, so match the Icon's `sdsSize` to the tag: `"s"` or `"xs"` for a small tag, `"l"` for a large one. Some icons exist at only one of those sizes, Star and Virus among them, and asking for one at a size it does not have renders nothing and logs an error.
+- Icons are drawn at the tag's icon size (12px in a medium tag, 10px in a small one) and in its icon color, whatever the icon itself asks for, so pass a bare Phosphor or `@czi-sds/icons` icon. The deprecated SDS Icon still works, as long as the icon exists at a small size.
+
+- Contrast is yours to check when you pass custom colors. SDS only guarantees it for its own intents.
+
+## Migrating from TagLegacy
+
+The Tag before SDS 25 is still exported as `TagLegacy`, so an app can switch its imports first and migrate each usage later. Its props map to the new Tag like this:
 
-- The two-value form of a custom `color` leaves the icon white rather than coloring it with the label, so it vanishes on a light fill; a tag with an icon wants the three-value form. On a secondary tag, custom colors also draw the border in the fill color, which hides it. Contrast is yours to check. SDS only guarantees it for its own intents.
+| Old prop                           | Replace with                                                                      |
+| ---------------------------------- | --------------------------------------------------------------------------------- |
+| `sdsType="primary"`                | `sdsStyle="solid"`, the default                                                   |
+| `sdsType="secondary"`              | `sdsStyle="outline"`                                                              |
+| `sdsStyle="rounded"` or `"square"` | Nothing: a tag with a label is always pill-shaped, and an icon-only tag is square |
+| `sdsSize="s"`                      | `size="small"`                                                                    |
+| `sdsSize="l"`                      | `size="medium"`, the default, which no longer needs an icon                       |
+| `hover={false}`                    | Nothing: a tag without an `onClick` or an `href` is static                        |
+| `tagColor`                         | `color`                                                                           |
+| `color={[label, background]}`      | Unchanged, though the icon now takes the label color rather than staying white    |
 
 ## Props
 
 Any custom SDS props and MUI props required for implementation are found on the table below. See the MUI documentation for additional optional props.
 
-| Name       | Type                                                                                                                                  | Default      | Description                                                                                                                                                                                 |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `label`    | `string`                                                                                                                              | - (required) | The tag's text, and its accessible name. It is cut off with an ellipsis rather than wrapped when there is not room for it.                                                                  |
-| `color`    | `"info"` \| `"positive"` \| `"notice"` \| `"negative"` \| `"neutral"` \| `"beta"` \| `[string, string]` \| `[string, string, string]` | `"neutral"`  | The tag's intent, given either as one of the six names or as CSS colors: 1. [label color, background color]: the icon stays white 2. [label color, background color, icon color]            |
-| `sdsType`  | `"primary"` \| `"secondary"`                                                                                                          | `"primary"`  | primary fills the tag with the intent color and sets the label white. secondary tints the fill and keeps the label and a 1px border in the intent color.                                    |
-| `sdsStyle` | `"square"` \| `"rounded"`                                                                                                             | `"square"`   | The shape of the tag. The design guidance treats rounded as the default for the system, so it is usually worth passing.                                                                     |
-| `sdsSize`  | `"s" \| "l"`                                                                                                                          | `"s"`        | The size of the tag: an 11px label with a 12px icon, or a 13px label with a 24px icon. A large tag has to have an icon.                                                                     |
-| `icon`     | `JSX.Element`                                                                                                                         | -            | An icon on the leading edge, usually an SDS Icon. It is drawn at the tag's icon size whatever size it asks for, so match its `sdsSize` to the tag.                                          |
-| `hover`    | `boolean`                                                                                                                             | `true`       | Whether the tag responds to the pointer with a darker fill and a pointer cursor. False removes the tag from pointer events altogether, which also keeps a surrounding Tooltip from opening. |
-| `onClick`  | `(event) => void`                                                                                                                     | -            | MUI's prop. Makes the tag a button: a tab stop that answers Enter and Space.                                                                                                                |
-| `onDelete` | `(event) => void`                                                                                                                     | -            | MUI's prop. Adds a delete control, drawn with MUI's Cancel icon rather than the SDS X. Use TagFilter for a removable tag instead.                                                           |
+| Name           | Type                                                                                                                                                | Default      | Description                                                                                                                                                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`        | `string`                                                                                                                                            | - (required) | The tag's text, and its accessible name. It is cut off with an ellipsis rather than wrapped, so keep it to a word or two. An icon-only tag still needs it: the text is hidden from view but read by screen readers. |
+| `sdsStyle`     | `"solid"` \| `"outline"`                                                                                                                            | `"solid"`    | `solid` fills the tag with the intent color. `outline` tints the fill and draws the label, the icons and a 1px border in the intent color.                                                                          |
+| `size`         | `"small"` \| `"medium"`                                                                                                                             | `"medium"`   | `medium` is 24px tall with a 13px label and 12px icons, `small` is 20px tall with a 10px label and 10px icons.                                                                                                      |
+| `color`        | `"accent"` \| `"beta"` \| `"info"` \| `"negative"` \| `"neutral"` \| `"notice"` \| `"positive"` \| `[string, string]` \| `[string, string, string]` | `"neutral"`  | One of the seven intents, or CSS colors for a tag the intents do not cover: `[label, background]` or `[label, background, icon]`. The icon takes the label color when the third value is left out.                  |
+| `icon`         | `ReactElement`                                                                                                                                      | -            | An icon on the leading edge, usually a Phosphor or `@czi-sds/icons` icon. The tag draws it at its own icon size and color.                                                                                          |
+| `iconOnly`     | `boolean`                                                                                                                                           | `false`      | Draws only the icon, in a square tag. The label is hidden from view but stays the tag's accessible name. Has no effect without an icon.                                                                             |
+| `showLinkIcon` | `boolean`                                                                                                                                           | `false`      | Adds an arrow after the label to say the tag leads somewhere. Usually paired with `href`, though a tag can be a link without it.                                                                                    |
+| `href`         | `string`                                                                                                                                            | -            | Turns the tag into a link. It renders as an `<a>` unless `component` says otherwise, as with a router's link component.                                                                                             |
+| `target`       | `string`                                                                                                                                            | -            | Where the link opens. `_blank` also sets `rel="noopener noreferrer"`.                                                                                                                                               |
+| `rel`          | `string`                                                                                                                                            | -            | The link's relationship to the current page.                                                                                                                                                                        |
+| `disabled`     | `boolean`                                                                                                                                           | `false`      | Greys the tag out. On a clickable tag or a link it also takes the tag out of the tab order.                                                                                                                         |
+| `onClick`      | `(event) => void`                                                                                                                                   | -            | MUI's prop. Makes the tag a button: a tab stop that answers Enter and Space, with hover and pressed states.                                                                                                         |
+| `onDelete`     | `(event) => void`                                                                                                                                   | -            | MUI's prop. Adds a delete control, drawn with MUI's Cancel icon. Use Chip for a removable tag instead.                                                                                                              |