From 33ea7fb3017d850044c2c6dc5482ac5de53a9721 Mon Sep 17 00:00:00 2001 From: Charles de Dreuille Date: Sun, 19 Apr 2026 09:54:19 +0200 Subject: [PATCH] docs(ui): update Header docs with tags, description, and metadata props Add new props to the Header API reference and examples on ui.backstage.io. Also adds deprecated badge support to the shared PropsTable component so the breadcrumbs prop is visually marked as deprecated. Signed-off-by: Charles de Dreuille Made-with: Cursor --- .../src/app/components/header/components.tsx | 36 +++++++++++++++ docs-ui/src/app/components/header/page.mdx | 32 +++++++++++-- .../components/header/props-definition.tsx | 45 +++++++++++++++++++ docs-ui/src/app/components/header/snippets.ts | 36 +++++++++++++-- docs-ui/src/components/Chip/Chip.tsx | 8 +++- docs-ui/src/components/Chip/styles.module.css | 10 +++++ .../src/components/PropsTable/PropsTable.tsx | 7 ++- docs-ui/src/utils/propDefs.ts | 1 + 8 files changed, 166 insertions(+), 9 deletions(-) diff --git a/docs-ui/src/app/components/header/components.tsx b/docs-ui/src/app/components/header/components.tsx index 26dc715a5d..4eb911e143 100644 --- a/docs-ui/src/app/components/header/components.tsx +++ b/docs-ui/src/app/components/header/components.tsx @@ -29,10 +29,25 @@ const breadcrumbs = [ }, ]; +const tags = [ + { label: 'TypeScript' }, + { label: 'Platform', href: '/platform' }, + { label: 'Gold' }, +]; + +const metadata = [ + { label: 'Owner', value: 'platform-team' }, + { label: 'Type', value: 'website' }, + { label: 'Tier', value: 'gold' }, +]; + export const WithEverything = () => (
( ); +export const WithTags = () => ( + +
+ +); + +export const WithDescription = () => ( + +
+ +); + +export const WithMetadata = () => ( + +
+ +); + export const WithLongBreadcrumbs = () => (
diff --git a/docs-ui/src/app/components/header/page.mdx b/docs-ui/src/app/components/header/page.mdx index 9e02b70a70..a38aac2864 100644 --- a/docs-ui/src/app/components/header/page.mdx +++ b/docs-ui/src/app/components/header/page.mdx @@ -5,6 +5,9 @@ import { WithEverything, WithLongBreadcrumbs, WithTabs, + WithTags, + WithDescription, + WithMetadata, WithCustomActions, WithMenu, } from './components'; @@ -13,6 +16,9 @@ import { usage, defaultSnippet, withTabs, + withTags, + withDescription, + withMetadata, withBreadcrumbs, withCustomActions, withMenu, @@ -24,7 +30,7 @@ import { ChangelogComponent } from '@/components/ChangelogComponent'; } code={defaultSnippet} /> @@ -39,11 +45,23 @@ import { ChangelogComponent } from '@/components/ChangelogComponent'; ## Examples -### Breadcrumbs +### Tags -Labels are truncated at 240px. +Tags are rendered above the title. Each tag with an `href` renders as a link; tags without `href` render as plain text. Tags are separated by a small circle divider. -} code={withBreadcrumbs} /> +} code={withTags} /> + +### Description + +The description accepts a markdown string. Only inline elements are supported — links, bold, and italic. + +} code={withDescription} /> + +### Metadata + +Key-value pairs displayed below the description. + +} code={withMetadata} /> ### Tabs @@ -61,6 +79,12 @@ Use `customActions` to add a dropdown menu. } code={withMenu} /> +### Breadcrumbs (deprecated) + +The `breadcrumbs` prop is deprecated and will be removed in a future release. Labels are truncated at 240px. + +} code={withBreadcrumbs} /> + diff --git a/docs-ui/src/app/components/header/props-definition.tsx b/docs-ui/src/app/components/header/props-definition.tsx index 0acc7d30ae..3106e0853b 100644 --- a/docs-ui/src/app/components/header/props-definition.tsx +++ b/docs-ui/src/app/components/header/props-definition.tsx @@ -5,6 +5,50 @@ export const headerPagePropDefs: Record = { type: 'string', description: 'Page heading displayed in the header.', }, + tags: { + type: 'complex', + description: + 'Items displayed above the title. Each tag renders as a link when href is provided, or as plain text otherwise. Tags are separated by a small circle divider.', + complexType: { + name: 'HeaderTag[]', + properties: { + label: { + type: 'string', + required: true, + description: 'Display text for the tag.', + }, + href: { + type: 'string', + required: false, + description: 'URL to navigate to when the tag is clicked.', + }, + }, + }, + }, + description: { + type: 'string', + description: + 'Markdown string rendered below the title. Only inline elements are supported: links, bold, and italic. Block-level markdown such as headings or lists is not rendered.', + }, + metadata: { + type: 'complex', + description: 'Key-value pairs displayed below the description.', + complexType: { + name: 'HeaderMetadataItem[]', + properties: { + label: { + type: 'string', + required: true, + description: 'The key label, displayed in bold.', + }, + value: { + type: 'ReactNode', + required: true, + description: 'The value to display alongside the label.', + }, + }, + }, + }, customActions: { type: 'enum', values: ['ReactNode'], @@ -49,6 +93,7 @@ export const headerPagePropDefs: Record = { }, breadcrumbs: { type: 'complex', + deprecated: true, description: 'Breadcrumb trail displayed above the title.', complexType: { name: 'HeaderBreadcrumb[]', diff --git a/docs-ui/src/app/components/header/snippets.ts b/docs-ui/src/app/components/header/snippets.ts index 8dfef0e69e..f0803ae7c7 100644 --- a/docs-ui/src/app/components/header/snippets.ts +++ b/docs-ui/src/app/components/header/snippets.ts @@ -4,9 +4,16 @@ export const usage = `import { Header } from '@backstage/ui'; export const defaultSnippet = `
} />`; + +export const withTags = `
`; + +export const withDescription = `
`; + +export const withMetadata = `
`; diff --git a/docs-ui/src/components/Chip/Chip.tsx b/docs-ui/src/components/Chip/Chip.tsx index b348b46c32..a1d9d75e62 100644 --- a/docs-ui/src/components/Chip/Chip.tsx +++ b/docs-ui/src/components/Chip/Chip.tsx @@ -4,12 +4,18 @@ import styles from './styles.module.css'; export const Chip = ({ children, head = false, + deprecated = false, }: { children: ReactNode; head?: boolean; + deprecated?: boolean; }) => { return ( - + {children} ); diff --git a/docs-ui/src/components/Chip/styles.module.css b/docs-ui/src/components/Chip/styles.module.css index d752ae2602..2446e46388 100644 --- a/docs-ui/src/components/Chip/styles.module.css +++ b/docs-ui/src/components/Chip/styles.module.css @@ -14,6 +14,11 @@ color: #2563eb; } +.deprecated { + background-color: #fff4e5; + color: #b45309; +} + [data-theme-mode='dark'] .chip { background-color: #2c2c2c; color: #fff; @@ -22,3 +27,8 @@ [data-theme-mode='dark'] .chip.head { background-color: #33405b; } + +[data-theme-mode='dark'] .chip.deprecated { + background-color: #3d2a10; + color: #fbbf24; +} diff --git a/docs-ui/src/components/PropsTable/PropsTable.tsx b/docs-ui/src/components/PropsTable/PropsTable.tsx index a8af2ad116..db5759d0e3 100644 --- a/docs-ui/src/components/PropsTable/PropsTable.tsx +++ b/docs-ui/src/components/PropsTable/PropsTable.tsx @@ -52,7 +52,12 @@ export const PropsTable = >({ switch (column) { case 'prop': - return {propName}; + return ( +
+ {propName} + {propData.deprecated && deprecated} +
+ ); case 'type': return ( diff --git a/docs-ui/src/utils/propDefs.ts b/docs-ui/src/utils/propDefs.ts index f714dd0d08..f92f1a37eb 100644 --- a/docs-ui/src/utils/propDefs.ts +++ b/docs-ui/src/utils/propDefs.ts @@ -44,6 +44,7 @@ export type PropDef = { required?: boolean; responsive?: boolean; description?: ReactNode; + deprecated?: boolean; }; export { breakpoints };