feat: Allow lists to appear in white on a dark background

packages/css/src/components/ordered-list/ordered-list.scss

@@ -36,6 +36,10 @@
   }
 }
 
+.amsterdam-ordered-list--inverse-color:not(.amsterdam-ordered-list--no-markers) {
+  color: var(--amsterdam-ordered-list-inverse-color);
+}
+
 /** A nested list has a different marker and less indentation for correct alignment. */
 :is(.amsterdam-ordered-list, .amsterdam-unordered-list) .amsterdam-ordered-list {
   list-style-type: var(--amsterdam-ordered-list-ordered-list-list-style-type);

packages/css/src/components/unordered-list/unordered-list.scss

@@ -36,6 +36,10 @@
   }
 }
 
+.amsterdam-unordered-list--inverse-color:not(.amsterdam-unordered-list--no-markers) {
+  color: var(--amsterdam-unordered-list-inverse-color);
+}
+
 /** A nested list has a different marker and less indentation for correct alignment. */
 :is(.amsterdam-ordered-list, .amsterdam-unordered-list) .amsterdam-unordered-list {
   list-style-type: var(--amsterdam-unordered-list-unordered-list-list-style-type);

packages/react/src/OrderedList/OrderedList.tsx

@@ -10,17 +10,26 @@ import { OrderedListItem } from './OrderedListItem'
 
 export type OrderedListProps = {
   markers?: boolean
+  inverseColor?: boolean
 } & PropsWithChildren<OlHTMLAttributes<HTMLOListElement>>
 
 type OrderedListComponent = {
   Item: typeof OrderedListItem
 } & ForwardRefExoticComponent<OrderedListProps & RefAttributes<HTMLOListElement>>
 
 export const OrderedList = forwardRef(
-  ({ children, markers = true, className, ...restProps }: OrderedListProps, ref: ForwardedRef<HTMLOListElement>) => (
+  (
+    { children, className, inverseColor, markers = true, ...restProps }: OrderedListProps,
+    ref: ForwardedRef<HTMLOListElement>,
+  ) => (
     <ol
       ref={ref}
-      className={clsx('amsterdam-ordered-list', !markers && 'amsterdam-ordered-list--no-markers', className)}
+      className={clsx(
+        'amsterdam-ordered-list',
+        inverseColor && 'amsterdam-ordered-list--inverse-color',
+        !markers && 'amsterdam-ordered-list--no-markers',
+        className,
+      )}
       {...restProps}
     >
       {children}

packages/react/src/UnorderedList/UnorderedList.tsx

@@ -9,6 +9,7 @@ import type { ForwardedRef, ForwardRefExoticComponent, HTMLAttributes, PropsWith
 import { UnorderedListItem } from './UnorderedListItem'
 
 export type UnorderedListProps = {
+  inverseColor?: boolean
   markers?: boolean
 } & PropsWithChildren<HTMLAttributes<HTMLUListElement>>
 
@@ -17,11 +18,19 @@ type UnorderedListComponent = {
 } & ForwardRefExoticComponent<UnorderedListProps & RefAttributes<HTMLUListElement>>
 
 export const UnorderedList = forwardRef(
-  ({ children, markers = true, className, ...restProps }: UnorderedListProps, ref: ForwardedRef<HTMLUListElement>) => {
+  (
+    { children, className, inverseColor, markers = true, ...restProps }: UnorderedListProps,
+    ref: ForwardedRef<HTMLUListElement>,
+  ) => {
     return (
       <ul
         ref={ref}
-        className={clsx('amsterdam-unordered-list', !markers && 'amsterdam-unordered-list--no-markers', className)}
+        className={clsx(
+          'amsterdam-unordered-list',
+          inverseColor && 'amsterdam-unordered-list--inverse-color',
+          !markers && 'amsterdam-unordered-list--no-markers',
+          className,
+        )}
         {...restProps}
       >
         {children}

proprietary/tokens/src/components/amsterdam/ordered-list.tokens.json

@@ -6,6 +6,7 @@
       "font-size": { "value": "{amsterdam.typography.text-level.5.font-size}" },
       "font-weight": { "value": "{amsterdam.typography.font-weight.normal}" },
       "gap": { "value": "0.75rem" },
+      "inverse-color": { "value": "{amsterdam.color.primary-white}" },
       "line-height": { "value": "{amsterdam.typography.text-level.5.line-height}" },
       "list-style-type": { "value": "decimal" },
       "item": {

proprietary/tokens/src/components/amsterdam/unordered-list.tokens.json

@@ -6,6 +6,7 @@
       "font-size": { "value": "{amsterdam.typography.text-level.5.font-size}" },
       "font-weight": { "value": "{amsterdam.typography.font-weight.normal}" },
       "gap": { "value": "0.75rem" },
+      "inverse-color": { "value": "{amsterdam.color.primary-white}" },
       "line-height": { "value": "{amsterdam.typography.text-level.5.line-height}" },
       "list-style-type": { "value": "'\\2022'" },
       "item": {

storybook/storybook-react/src/OrderedList/OrderedList.docs.mdx

@@ -48,3 +48,11 @@ Therefore, it does not define typography for the items.
 For example, here are three news articles:
 
 <Canvas of={OrderedListStories.WithoutMarkers} />
+
+### Inverse colour
+
+Set the `inverseColor` prop if the List sits on a dark background.
+This ensures the colour of the text provides enough contrast.
+When nesting lists, set the prop on all lists.
+
+<Canvas of={OrderedListStories.InverseColor} />

storybook/storybook-react/src/OrderedList/OrderedList.stories.tsx

@@ -104,3 +104,16 @@ export const WithoutMarkers: Story = {
     markers: false,
   },
 }
+
+export const InverseColor: Story = {
+  args: {
+    inverseColor: true,
+  },
+  decorators: [
+    (Story, context) => (
+      <div className={context.args.inverseColor ? 'amsterdam-docs-dark-background' : undefined}>
+        <Story />
+      </div>
+    ),
+  ],
+}

storybook/storybook-react/src/UnorderedList/UnorderedList.docs.mdx

@@ -5,6 +5,7 @@ import README from "../../../../packages/css/src/components/unordered-list/READM
 <Meta of={UnorderedListStories} />
 
 <Markdown>{README}</Markdown>
+
 ## Examples
 
 ### Default
@@ -35,3 +36,11 @@ Therefore, this variant does not define typography for the items.
 This example is based on the top tasks on the homepage of the website:
 
 <Canvas of={UnorderedListStories.WithoutMarkers} />
+
+### Inverse colour
+
+Set the `inverseColor` prop if the List sits on a dark background.
+This ensures the colour of the text provides enough contrast.
+When nesting lists, set the prop on all lists.
+
+<Canvas of={UnorderedListStories.InverseColor} />

storybook/storybook-react/src/UnorderedList/UnorderedList.stories.tsx

@@ -117,3 +117,16 @@ export const WithoutMarkers: Story = {
     markers: false,
   },
 }
+
+export const InverseColor: Story = {
+  args: {
+    inverseColor: true,
+  },
+  decorators: [
+    (Story, context) => (
+      <div className={context.args.inverseColor ? 'amsterdam-docs-dark-background' : undefined}>
+        <Story />
+      </div>
+    ),
+  ],
+}