@kaizen/components 3.3.14 → 3.3.16

package/dist/cjs/src/TextArea/TextArea.module.css.cjs

@@ -1,14 +1,14 @@
 'use strict';
 
 var modules_f168227d = {
-  "wrapper": "TextArea_module_wrapper__be744297",
-  "wrapperAutogrow": "TextArea_module_wrapperAutogrow__be744297",
-  "textarea": "TextArea_module_textarea__be744297",
-  "textareaAutogrow": "TextArea_module_textareaAutogrow__be744297",
-  "default": "TextArea_module_default__be744297",
-  "error": "TextArea_module_error__be744297",
-  "caution": "TextArea_module_caution__be744297",
-  "disabled": "TextArea_module_disabled__be744297",
-  "reversed": "TextArea_module_reversed__be744297"
+  "wrapper": "TextArea_module_wrapper__36440826",
+  "wrapperAutogrow": "TextArea_module_wrapperAutogrow__36440826",
+  "textarea": "TextArea_module_textarea__36440826",
+  "textareaAutogrow": "TextArea_module_textareaAutogrow__36440826",
+  "default": "TextArea_module_default__36440826",
+  "error": "TextArea_module_error__36440826",
+  "caution": "TextArea_module_caution__36440826",
+  "disabled": "TextArea_module_disabled__36440826",
+  "reversed": "TextArea_module_reversed__36440826"
 };
 module.exports = modules_f168227d;

package/dist/esm/src/TextArea/TextArea.module.css.mjs

@@ -1,12 +1,12 @@
 var modules_f168227d = {
-  "wrapper": "TextArea_module_wrapper__be744297",
-  "wrapperAutogrow": "TextArea_module_wrapperAutogrow__be744297",
-  "textarea": "TextArea_module_textarea__be744297",
-  "textareaAutogrow": "TextArea_module_textareaAutogrow__be744297",
-  "default": "TextArea_module_default__be744297",
-  "error": "TextArea_module_error__be744297",
-  "caution": "TextArea_module_caution__be744297",
-  "disabled": "TextArea_module_disabled__be744297",
-  "reversed": "TextArea_module_reversed__be744297"
+  "wrapper": "TextArea_module_wrapper__36440826",
+  "wrapperAutogrow": "TextArea_module_wrapperAutogrow__36440826",
+  "textarea": "TextArea_module_textarea__36440826",
+  "textareaAutogrow": "TextArea_module_textareaAutogrow__36440826",
+  "default": "TextArea_module_default__36440826",
+  "error": "TextArea_module_error__36440826",
+  "caution": "TextArea_module_caution__36440826",
+  "disabled": "TextArea_module_disabled__36440826",
+  "reversed": "TextArea_module_reversed__36440826"
 };
 export { modules_f168227d as default };

package/dist/styles.css

@@ -149,7 +149,7 @@
 @layer kz-components{.Tab_module_tab__ce4d43df{display:inline-flex;align-items:center;border:2px solid transparent;border-bottom:0;border-top-left-radius:var(--border-borderless-border-radius);border-top-right-radius:var(--border-borderless-border-radius);background:transparent;white-space:nowrap;text-decoration:none;padding:var(--spacing-md) var(--spacing-md);margin:0;font-family:var(--typography-heading-4-font-family);font-size:var(--typography-heading-4-font-size);font-weight:var(--typography-heading-4-font-weight);line-height:var(--typography-heading-4-line-height);letter-spacing:var(--typography-heading-4-letter-spacing);color:var(--color-purple-800);cursor:default;&:focus{outline:none}&:focus-visible{color:var(--color-blue-500);border-color:var(--color-blue-500)}&[data-disabled]{opacity:.3}&:not(:first-child){margin-inline-start:var(--spacing-xs)}&:not([data-disabled]):hover{background:var(--color-blue-200);color:var(--color-blue-500)}&:not([data-disabled]):active{background:var(--color-blue-100)}}.Tab_module_tab__ce4d43df[data-selected]{position:relative;color:var(--color-blue-500);&:before{content:"";display:block;border-top-left-radius:5px;border-top-right-radius:5px;background-color:currentcolor;height:5px;width:100%;position:absolute;left:0;right:0;bottom:0}}.Tab_module_badge__ce4d43df{margin-inline-start:var(--spacing-sm);display:inline-flex;align-items:center}@media (forced-colors:active){.Tab_module_tab__ce4d43df{border:2px solid transparent;&:focus-visible:after{content:"";position:absolute;background:transparent;border-radius:var(--border-focus-ring-border-radius);border-width:var(--border-focus-ring-border-width);border-style:var(--border-focus-ring-border-style);border-color:transparent;inset:-2px}}.Tab_module_tab__ce4d43df[data-selected]:before{content:"";position:absolute;left:0;right:0;bottom:0;border-bottom:2px solid transparent}}}
 @layer kz-components{.TabList_module_container__7ce81ce7{position:relative}.TabList_module_tabList__7ce81ce7{border-bottom:1px solid var(--color-gray-300);padding:var(--spacing-6) 0 0;width:100%;height:100%;overflow-x:scroll;white-space:nowrap;scrollbar-width:none;scroll-behavior:smooth}.TabList_module_noPadding__7ce81ce7{padding:0}.TabList_module_leftArrow__7ce81ce7,.TabList_module_rightArrow__7ce81ce7{--icon-size:24;display:flex;align-items:center;justify-content:center;position:absolute;z-index:1030;background:var(--color-white);inset-block:0 1px;width:48px;cursor:default;user-select:none}.TabList_module_leftArrow__7ce81ce7{left:0}.TabList_module_leftArrow__7ce81ce7,.TabList_module_leftArrow__7ce81ce7:hover{border-right:1px solid var(--color-gray-300)}.TabList_module_rightArrow__7ce81ce7{right:0}.TabList_module_rightArrow__7ce81ce7,.TabList_module_rightArrow__7ce81ce7:hover{border-left:1px solid var(--color-gray-300)}.TabList_module_leftArrow__7ce81ce7:hover,.TabList_module_rightArrow__7ce81ce7:hover{background:var(--color-blue-200);color:var(--color-blue-500)}.TabList_module_leftArrow__7ce81ce7:active,.TabList_module_rightArrow__7ce81ce7:active{background:var(--color-blue-100);color:var(--color-blue-500)}}
 @layer kz-components{.TabPanel_module_tabPanel__931e68c3{border:2px solid transparent;&:focus{outline:none}&:focus-visible{border-color:var(--color-blue-500);border-radius:var(--border-focus-ring-border-radius)}}}
-@layer kz-components{.TextArea_module_wrapper__be744297{font-family:var(--typography-paragraph-body-font-family);font-size:var(--typography-paragraph-body-font-size);font-weight:var(--typography-paragraph-body-font-weight);line-height:var(--typography-paragraph-body-line-height);letter-spacing:var(--typography-paragraph-body-letter-spacing);color:var(--color-purple-800-rgb)}.TextArea_module_wrapperAutogrow__be744297{display:grid}.TextArea_module_wrapperAutogrow__be744297:after{content:attr(data-value) " ";white-space:pre-wrap;visibility:hidden}.TextArea_module_textarea__be744297,.TextArea_module_wrapperAutogrow__be744297:after{border:var(--border-solid-border-width) var(--border-solid-border-style) var(--color-gray-500);border-radius:var(--border-solid-border-radius);padding:var(--spacing-sm);box-sizing:border-box;width:100%;font:inherit}.TextArea_module_textareaAutogrow__be744297,.TextArea_module_wrapperAutogrow__be744297:after{grid-area:2/1}.TextArea_module_textarea__be744297{display:block;border:var(--border-solid-border-width) var(--border-solid-border-style) var(--color-gray-500);border-radius:var(--border-solid-border-radius);padding:var(--spacing-sm);resize:vertical;&:focus{outline:var(--border-focus-ring-border-width) var(--border-focus-ring-border-style) var(--color-blue-500);outline-offset:1px}&:disabled{border-color:rgb(var(--color-gray-500-rgb),.3);resize:none}}.TextArea_module_textareaAutogrow__be744297{overflow:hidden}.TextArea_module_default__be744297{&:not(.TextArea_module_error__be744297,.TextArea_module_caution__be744297){&:disabled{border-color:rgb(var(--color-gray-500-rgb),.3)}}&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){background-color:var(--color-gray-200);border-color:var(--color-gray-600)}&.TextArea_module_error__be744297{border-color:var(--color-red-500);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-red-500)}}&.TextArea_module_caution__be744297{border-color:var(--color-yellow-600);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-yellow-600)}}&.TextArea_module_disabled__be744297{background-color:var(--color-white);border-color:rgb(var(--color-gray-500-rgb),.3);color:rgb(var(--color-purple-800-rgb),.3)}}.TextArea_module_reversed__be744297{border-color:rgb(var(--color-white-rgb),.65);background:transparent;color:var(--color-white);&:focus{outline-color:var(--color-blue-300)}&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){background:rgb(var(--color-white-rgb),.1);border-color:var(--color-white)}&.TextArea_module_error__be744297{border-color:var(--color-red-300);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-red-300)}}&.TextArea_module_caution__be744297{border-color:var(--color-yellow-400);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-yellow-400)}}&.TextArea_module_disabled__be744297{background:transparent;border-color:rgb(var(--color-white-rgb),.3);color:rgb(var(--color-white-rgb),.3)}}}
+@layer kz-components{.TextArea_module_wrapper__36440826{font-family:var(--typography-paragraph-body-font-family);font-size:var(--typography-paragraph-body-font-size);font-weight:var(--typography-paragraph-body-font-weight);line-height:var(--typography-paragraph-body-line-height);letter-spacing:var(--typography-paragraph-body-letter-spacing);color:var(--color-purple-800-rgb)}.TextArea_module_wrapperAutogrow__36440826{display:grid}.TextArea_module_wrapperAutogrow__36440826:after{content:attr(data-value) " ";white-space:pre-wrap;visibility:hidden}.TextArea_module_textarea__36440826,.TextArea_module_wrapperAutogrow__36440826:after{border:var(--border-solid-border-width) var(--border-solid-border-style) var(--color-gray-500);border-radius:var(--border-solid-border-radius);padding:var(--spacing-sm);box-sizing:border-box;width:100%;font:inherit;overflow-wrap:anywhere}.TextArea_module_textareaAutogrow__36440826,.TextArea_module_wrapperAutogrow__36440826:after{grid-area:2/1}.TextArea_module_textarea__36440826{display:block;border:var(--border-solid-border-width) var(--border-solid-border-style) var(--color-gray-500);border-radius:var(--border-solid-border-radius);padding:var(--spacing-sm);resize:vertical;&:focus{outline:var(--border-focus-ring-border-width) var(--border-focus-ring-border-style) var(--color-blue-500);outline-offset:1px}&:disabled{border-color:rgb(var(--color-gray-500-rgb),.3);resize:none}}.TextArea_module_textareaAutogrow__36440826{overflow:hidden}.TextArea_module_default__36440826{&:not(.TextArea_module_error__36440826,.TextArea_module_caution__36440826){&:disabled{border-color:rgb(var(--color-gray-500-rgb),.3)}}&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){background-color:var(--color-gray-200);border-color:var(--color-gray-600)}&.TextArea_module_error__36440826{border-color:var(--color-red-500);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-red-500)}}&.TextArea_module_caution__36440826{border-color:var(--color-yellow-600);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-yellow-600)}}&.TextArea_module_disabled__36440826{background-color:var(--color-white);border-color:rgb(var(--color-gray-500-rgb),.3);color:rgb(var(--color-purple-800-rgb),.3)}}.TextArea_module_reversed__36440826{border-color:rgb(var(--color-white-rgb),.65);background:transparent;color:var(--color-white);&:focus{outline-color:var(--color-blue-300)}&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){background:rgb(var(--color-white-rgb),.1);border-color:var(--color-white)}&.TextArea_module_error__36440826{border-color:var(--color-red-300);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-red-300)}}&.TextArea_module_caution__36440826{border-color:var(--color-yellow-400);&:focus:not([disabled]),&:hover:focus:not([disabled]),&:hover:not([disabled]){border-color:var(--color-yellow-400)}}&.TextArea_module_disabled__36440826{background:transparent;border-color:rgb(var(--color-white-rgb),.3);color:rgb(var(--color-white-rgb),.3)}}}
 @layer kz-components{.TextAreaField_module_message__095b2956.TextAreaField_module_disabled__095b2956{opacity:.3}.TextAreaField_module_textareaLabel__095b2956{margin-bottom:var(--spacing-xs,.375rem)}.TextAreaField_module_textareaLabelProminent__095b2956{margin-bottom:0}}
 @layer kz-components{.GenericTile_module_root__8e7442cc{perspective:800px}.GenericTile_module_tile__8e7442cc{position:relative;width:330px;height:370px;transition:transform var(--animation-duration-slow,.4s) var(--animation-easing-function-ease-in-out,cubic-bezier(.455,.03,.515,.955));transform-style:preserve-3d;box-shadow:var(--shadow-small-box-shadow);border-radius:7px;background-color:var(--color-white);[data-tile-grid] &{width:auto}@media (width <= 767px){width:100%;min-width:226px;max-width:370px}@media (width <= 480px){max-width:100%}}.GenericTile_module_titleMeta__8e7442cc{padding-top:var(--spacing-4)}.GenericTile_module_face__8e7442cc{position:absolute;box-sizing:border-box;display:flex;flex-direction:column;align-items:center;width:100%;height:100%;backface-visibility:hidden;border:var(--border-width-1) solid var(--generic-tile-border-color);border-radius:var(--border-solid-border-radius);background-color:var(--generic-tile-background-color);*{backface-visibility:hidden}}.GenericTile_module_faceFront__8e7442cc{justify-content:space-between;padding:var(--spacing-xl) var(--spacing-md) var(--spacing-md)}.GenericTile_module_faceBack__8e7442cc{--generic-tile-border-color:var(--color-blue-400);--generic-tile-background-color:var(--color-blue-100);padding-top:var(--spacing-xl);transform:rotateY(180deg)}.GenericTile_module_default__8e7442cc{--generic-tile-border-color:var(--color-gray-500);--generic-tile-background-color:var(--color-white)}.GenericTile_module_expertAdvice__8e7442cc{--generic-tile-border-color:var(--color-purple-400);--generic-tile-background-color:var(--color-purple-100)}.GenericTile_module_isFlipped__8e7442cc{transform:rotateY(179deg)}.GenericTile_module_title__8e7442cc{text-align:center;padding-bottom:var(--spacing-sm);backface-visibility:hidden}.GenericTile_module_actions__8e7442cc{display:flex}.GenericTile_module_informationBtn__8e7442cc{inset-block-start:0;inset-inline-end:0;position:absolute;color:rgb(var(--color-purple-800-rgb),.5)}.GenericTile_module_information__8e7442cc{display:flex;padding-bottom:var(--spacing-md);padding-right:var(--spacing-md);padding-left:var(--spacing-md);flex-direction:column;align-items:center;justify-content:space-between;box-sizing:border-box;width:100%;height:100%;text-align:left;border-radius:0 0 7px 7px}.GenericTile_module_footer__8e7442cc{display:flex;align-items:center;justify-content:center;margin-top:var(--spacing-sm);height:var(--spacing-xl)}}
 @layer kz-components{.MultiActionTile_module_actions__7f3718a6{display:flex}.MultiActionTile_module_secondaryAction__7f3718a6{margin-inline-end:var(--spacing-8)}}

package/dist/types/TitleBlock/types.d.ts

@@ -16,6 +16,11 @@ import { type NavigationTabProps } from './subcomponents/NavigationTabs';
 export type TitleBlockProps = {
     children?: React.ReactNode;
     title: string;
+    /**
+     * `light` is the recommended variant for new implementations. Leaving `variant`
+     * unset falls back to the default purple background.
+     *
+     */
     variant?: TitleBlockVariant;
     breadcrumb?: TitleBlockBreadcrumbType;
     avatar?: JSX.Element | TitleBlockAvatarProps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "3.3.14",
+  "version": "3.3.16",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -103,16 +103,16 @@
     "lodash.debounce": "^4.0.8",
     "nanobus": "^4.5.0",
     "prosemirror-commands": "^1.7.2",
-    "prosemirror-history": "^1.5.0",
+    "prosemirror-history": "^1.5.1",
     "prosemirror-inputrules": "^1.5.1",
     "prosemirror-keymap": "^1.2.3",
-    "prosemirror-model": "^1.25.11",
-    "prosemirror-schema-basic": "^1.2.4",
+    "prosemirror-model": "^1.25.12",
+    "prosemirror-schema-basic": "^1.2.5",
     "prosemirror-schema-list": "^1.5.1",
     "prosemirror-state": "^1.4.4",
-    "prosemirror-transform": "^1.12.1",
+    "prosemirror-transform": "^1.12.2",
     "prosemirror-utils": "^1.2.2",
-    "prosemirror-view": "^1.42.3",
+    "prosemirror-view": "^1.42.6",
     "react-animate-height": "^3.2.4",
     "react-aria": "^3.41.1",
     "react-aria-components": "^1.10.1",
@@ -130,16 +130,16 @@
   },
   "devDependencies": {
     "@cultureamp/frontend-apis": "13.3.0",
-    "@cultureamp/i18n-react-intl": "^4.6.4",
+    "@cultureamp/i18n-react-intl": "^4.6.6",
     "@cultureamp/package-bundler": "^4.1.1",
     "@svgr/rollup": "^8.1.0",
-    "@testing-library/dom": "^10.4.1",
+    "@testing-library/dom": "^10.4.2",
     "@types/jest-axe": "^3.5.9",
     "@types/lodash.debounce": "^4.0.9",
     "@types/react-highlight": "^0.12.8",
     "@types/react-textfit": "^1.1.4",
     "@types/uuid": "^11.0.0",
-    "autoprefixer": "^10.5.6",
+    "autoprefixer": "^10.6.1",
     "concat-cli": "^4.0.0",
     "cssnano": "^7.1.9",
     "identity-obj-proxy": "^3.0.0",
@@ -149,21 +149,21 @@
     "postcss": "^8.5.28",
     "postcss-cli": "^11.0.1",
     "postcss-import": "^16.2.0",
-    "postcss-preset-env": "^11.5.2",
+    "postcss-preset-env": "^11.6.0",
     "postcss-scss": "^4.0.9",
     "query-string": "^9.5.1",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-highlight": "^0.15.0",
-    "react-intl": "^10.2.1",
-    "rollup": "^4.63.1",
+    "react-intl": "^10.2.2",
+    "rollup": "^4.64.0",
     "sass": "1.79.6",
     "serialize-query-params": "^2.0.4",
     "svgo": "^4.1.0",
     "ts-patch": "^3.3.0",
     "tslib": "^2.8.1",
-    "tsx": "^4.23.13",
-    "@kaizen/design-tokens": "11.0.18"
+    "tsx": "^4.23.15",
+    "@kaizen/design-tokens": "11.0.20"
   },
   "devDependenciesComments": {
     "sass": "Prevent deprecation warnings introduced in 1.80 as we plan to move away from sass",

package/src/Filter/Filter/_docs/Filter.stickersheet.stories.tsx

@@ -10,17 +10,6 @@ const IS_CHROMATIC = isChromatic()
 export default {
   title: 'Components/Filter Base',
   parameters: {
-    a11y: {
-      config: {
-        rules: [
-          {
-            // FIXME: dialog element should have an accessible name
-            id: 'aria-dialog-name',
-            enabled: false,
-          },
-        ],
-      },
-    },
     chromatic: { disable: false },
     controls: { disable: true },
   },

package/src/TextArea/TextArea.module.css

@@ -27,6 +27,7 @@
     box-sizing: border-box;
     width: 100%;
     font: inherit;
+    overflow-wrap: anywhere;
   }
 
   .textareaAutogrow,

package/src/TextArea/_docs/TextArea.stickersheet.stories.tsx

@@ -40,11 +40,20 @@ const StickerSheetTemplate: StickerSheetStory = {
         </StickerSheet.Row>
       </StickerSheet>
       <StickerSheet title="Autogrow">
-        <TextArea
-          rows={1}
-          value="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque mattis nisi sit amet consectetur ultricies. Vestibulum porta arcu vitae erat egestas pulvinar. Proin tincidunt mi ultricies risus ultrices semper. Donec consequat, mi at tincidunt mattis, felis metus semper metus, a imperdiet justo odio ac elit. Nulla et lacinia enim. Donec placerat, arcu a hendrerit iaculis, massa ante venenatis urna, vitae vestibulum massa orci et erat. Sed in cursus arcu. Fusce fringilla urna tincidunt risus sodales mollis. Ut sit amet mi vitae justo aliquam congue eget eu nisl. Mauris sit amet dolor fermentum, rutrum orci eget, feugiat mi. Etiam feugiat auctor augue, non volutpat nisi aliquet non. Praesent dignissim, lacus id iaculis porttitor, purus libero fermentum urna, in faucibus massa enim sed dui. Maecenas et nisi in nulla condimentum dictum. Maecenas tincidunt turpis non consequat pharetra. Suspendisse in auctor erat, vel ullamcorper elit. Nullam rutrum pharetra turpis, id luctus nisi sollicitudin ac. Maecenas sodales malesuada orci. Integer ultrices, nisi non blandit commodo, turpis enim iaculis ante, vel blandit diam sapien eget justo. Mauris scelerisque euismod quam, nec accumsan lorem venenatis vel. Sed rhoncus purus turpis, vel efficitur metus placerat et."
-          autogrow
-        />
+        <StickerSheet.Row header="Wraps on whitespace (container 320px)">
+          <div style={{ maxWidth: '320px', border: '1px dashed currentcolor' }}>
+            <TextArea
+              rows={1}
+              value="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque mattis nisi sit amet consectetur ultricies. Vestibulum porta arcu vitae erat egestas pulvinar."
+              autogrow
+            />
+          </div>
+        </StickerSheet.Row>
+        <StickerSheet.Row header="Long unbroken word (container 320px)">
+          <div style={{ maxWidth: '320px', border: '1px dashed currentcolor' }}>
+            <TextArea rows={1} value={'A'.repeat(100)} autogrow />
+          </div>
+        </StickerSheet.Row>
       </StickerSheet>
     </>
   ),

package/src/TextAreaField/_docs/TextAreaField.stickersheet.stories.tsx

@@ -57,6 +57,14 @@ const StickerSheetTemplate: StickerSheetStory = {
             </StickerSheet.Row>
           ))}
         </StickerSheet>
+
+        <StickerSheet title="Autogrow" isReversed={isReversed}>
+          <StickerSheet.Row header="Long unbroken word (container 320px)">
+            <div style={{ width: '320px', border: '1px dashed currentcolor' }}>
+              <TextAreaField {...defaultProps} autogrow rows={1} value={'A'.repeat(150)} />
+            </div>
+          </StickerSheet.Row>
+        </StickerSheet>
       </>
     )
   },

package/src/TitleBlock/_docs/TitleBlock--api-specification.mdx

@@ -17,14 +17,15 @@ import * as TitleBlockStories from './TitleBlock.stories'
 
 `TitleBlock` A consistent pattern to allow users to navigate and complete tasks easily.
 
-<Canvas of={TitleBlockStories.Playground} />
+<Canvas of={TitleBlockStories.LightVariant} />
 
 ## Props
 
 <Controls
-  of={TitleBlockStories.Playground}
+  of={TitleBlockStories.LightVariant}
   include={[
     'avatar',
+    //TODO: note as depreication per https://cultureamp.atlassian.net/browse/KZN-4538
     'breadcrumb',
     'defaultAction',
     'handleHamburgerClick',
@@ -32,13 +33,30 @@ import * as TitleBlockStories from './TitleBlock.stories'
     'primaryAction',
     'secondaryActions',
     'secondaryOverflowMenuItems',
+    'sticky',
     'surveyStatus',
     'title',
+    'variant',
   ]}
 />
 
 ## Options
 
+### variant
+
+```
+variant?: 'light' | 'admin' | 'education'
+```
+
+Controls the TitleBlock's background and text colour. `light`
+is the recommended value. Without passing it, the UI renders as the default
+purple variant. See
+[Usage Guidelines](/docs/components-titleblock-usage-guidelines--docs)
+for the full guidance.
+
+If you're rendering `NavigationTab`s alongside the TitleBlock, set the same
+`variant` on each tab. Tabs don't inherit from the TitleBlock.
+
 ### primaryAction
 
 The primary action (the "main" button in the top right) can either be a Button,
@@ -66,6 +84,18 @@ If you want it to be a Menu, pass in this object of type `MenuGroup`:
 Using the `label`, the Title Block will render a Button with a chevron icon and your `menuItems` will appear
 in the dropdown menu when you click it. (`MenuItemProps` is a type imported from the `Menu` component.)
 
+### defaultAction
+
+```
+type DefaultActionProps = TitleBlockButtonProps | TitleBlockCustomButtonProps
+```
+
+Renders a Button immediately to the left of `primaryAction`, in the same top
+row. Pass the Button's props as an object, same as `primaryAction`.
+
+Unlike `primaryAction`, `defaultAction` **can't be a menu group** There's no
+dropdown variant of the default action, so passing `menuItems` is invalid. It can take a `badge`, but the badge only renders on the full-width button: at tablet and ≤360px widths the default action collapses into a menu item and the badge isn't shown.
+
 ### secondaryActions & secondaryOverflowMenuItems
 
 Secondary Actions sit below the Primary Actions, and consist of

package/src/TitleBlock/_docs/TitleBlock--usage-guidelines.mdx

@@ -1,5 +1,6 @@
-import { Canvas, DocsStory, Meta, Controls } from '@storybook/blocks'
-import { ResourceLinks, KAIOInstallation, DosAndDonts, DoOrDont } from '~storybook/components'
+import { Canvas, DocsStory, Meta, Controls, Unstyled } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import { InlineNotification } from '~components/Notification'
 import * as TitleBlockStories from './TitleBlock.stories'
 
 <Meta title="Components/TitleBlock/Usage Guidelines" />
@@ -18,31 +19,106 @@ import * as TitleBlockStories from './TitleBlock.stories'
 
 A consistent pattern to allow users to navigate and complete tasks easily.
 
-<Canvas of={TitleBlockStories.Playground} />
+<Canvas of={TitleBlockStories.LightVariant} sourceState="hidden" />
 
 <Controls
-  of={TitleBlockStories.Playground}
-  include={['avatar', 'defaultAction', 'navigationTabs', 'primaryAction', 'title']}
+  of={TitleBlockStories.LightVariant}
+  include={[
+    'avatar',
+    'defaultAction',
+    'navigationTabs',
+    'primaryAction',
+    'sticky',
+    'title',
+    'variant',
+  ]}
 />
 
-## Examples
+## Variants
+
+<Unstyled>
+  <InlineNotification persistent variant="cautionary">
+    {
+      <>
+        <strong>
+          Passing <code>variant="light"</code> is the ongoing recommendation.
+        </strong>{' '}
+        When a variant isn't passed, TitleBlock falls back to the default purple variant.
+      </>
+    }
+  </InlineNotification>
+</Unstyled>
+
+### Light (recommended)
+
+<Canvas of={TitleBlockStories.LightVariant} sourceState="hidden" />
+
+**If you're using navigation tabs, set `variant="light"` on each
+`NavigationTab`** Tabs don't inherit the variant from the TitleBlock. set
+it in both places, or the tabs keep their purple background.
+
+```tsx
+<TitleBlock
+  variant="light"
+  title="Page title"
+  navigationTabs={[
+    <NavigationTab key="1" variant="light" text="Label" href="#" active />,
+    <NavigationTab key="2" variant="light" text="Label" href="#" />,
+  ]}
+/>
+```
 
-### Viewports
+### Default (purple)
 
-<Canvas of={TitleBlockStories.Viewports} />
+Shown for recognition only. Don't reach for this on new surfaces.
 
-### Long titles
+<Canvas of={TitleBlockStories.Playground} sourceState="hidden" />
+
+## Sticky behavior
+
+Setting `sticky` pins the TitleBlock's top strip to the top of its scroll
+container as the page scrolls, instead of letting it scroll away. Full
+mechanism, structure, and code for reserving space above the strip (for
+example, a banner) are covered in the
+[Sticky Banner guide](/docs/components-titleblock-sticky-banner--docs).
+
+**If your surface is adding Coach, turn `sticky` on.** A pinned top strip is a
+requirement when the header carries a Coach button.
+
+### Coach button placement
 
-<Canvas of={TitleBlockStories.HasLongTitle} />
+For teams adding Coach to a surface that already has a primary Call to action CTA:
 
-### Light Variant
+- **Coach is the primary action.** Pass it as `primaryAction`.
+- **Demote the existing primary CTA to `defaultAction`.** This is the slot
+  that renders immediately to the left of `primaryAction`, in the same top
+  row. Don't use `secondaryActions` or `secondaryOverflowMenuItems` for this.
+  Those render in a separate row below, alongside the navigation tabs, not
+  next to the primary and default actions.
+
+  TitleBlock predates current naming conventions, so `defaultAction` is
+  its term for what a modern component would call a secondary action: a
+  non-primary button rendered next to the primary one.
+
+- **Coach sits furthest right**, closest to the side panel. TitleBlock is
+  props-based and its action slots aren't reorderable, so passing Coach as
+  `primaryAction` gives you this placement automatically.
+
+## Examples
+
+### Long titles
 
-<Canvas of={TitleBlockStories.LightVariant} />
+<Canvas of={TitleBlockStories.HasLongTitleLightVariant} sourceState="hidden" />
 
-### Admin Variant
+### Default action limitations
 
-<Canvas of={TitleBlockStories.AdminVariant} />
+`primaryAction` and `defaultAction` both render in the top row, but they don't
+accept the same props:
 
-### Education Variant
+- **`defaultAction` accepts a `badge`.** Pass `badge: { text: '3' }` alongside
+  the label. It reaches the underlying button, so you also get its optional
+  `variant` and `reversed` fields.
+- **`defaultAction` can't be a dropdown.** Only `primaryAction` accepts a menu
+  group (`{ label, menuItems }`) and renders a button that opens a menu.
 
-<Canvas of={TitleBlockStories.EducationVariant} />
+<Canvas of={TitleBlockStories.WithDefaultActionBadge} sourceState="hidden" />

package/src/TitleBlock/_docs/TitleBlock.stories.tsx

@@ -30,6 +30,15 @@ const SECONDARY_ACTIONS = [
   },
 ]
 
+const LIGHT_NAVIGATION_TABS = [
+  <NavigationTab key="1" variant="light" text="Label" href="#" active />,
+  <NavigationTab key="2" variant="light" text="Label" href="#" />,
+  <NavigationTab key="3" variant="light" text="Label" href="#" />,
+  <NavigationTab key="4" variant="light" text="Label" href="#" />,
+  <NavigationTab key="5" variant="light" text="Label" href="#" />,
+  <NavigationTab key="6" variant="light" text="Label" href="#" />,
+]
+
 const viewports = {
   viewports: {
     default: {
@@ -181,12 +190,6 @@ export const Playground: Story = {
   },
 }
 
-export const Viewports: Story = {
-  parameters: {
-    viewport: viewports,
-    chromatic: chromaticViewports,
-  },
-}
 export const WithTabNavigation: Story = {
   parameters: {
     viewport: viewports,
@@ -222,6 +225,18 @@ export const HasLongTitle: Story = {
   args: { title: 'A long title with over thirty characters' },
 }
 
+export const HasLongTitleLightVariant: Story = {
+  parameters: {
+    viewport: viewports,
+    chromatic: { disable: true },
+  },
+  args: {
+    variant: 'light',
+    title: 'A long title with over thirty characters',
+    navigationTabs: LIGHT_NAVIGATION_TABS,
+  },
+}
+
 export const LightVariant: Story = {
   parameters: {
     docs: {
@@ -235,14 +250,7 @@ export const LightVariant: Story = {
   args: {
     variant: 'light',
     title: 'Light TitleBlock',
-    navigationTabs: [
-      <NavigationTab key="1" variant="light" text="Label" href="#" active />,
-      <NavigationTab key="2" variant="light" text="Label" href="#" />,
-      <NavigationTab key="3" variant="light" text="Label" href="#" />,
-      <NavigationTab key="4" variant="light" text="Label" href="#" />,
-      <NavigationTab key="5" variant="light" text="Label" href="#" />,
-      <NavigationTab key="6" variant="light" text="Label" href="#" />,
-    ],
+    navigationTabs: LIGHT_NAVIGATION_TABS,
   },
 }
 
@@ -553,20 +561,6 @@ export const StickerSheetBreadcrumbs: Story = {
         '#Breadcrumbs-focus-example [class^="TitleBlock-TitleBlock-module__breadcrumb"]',
       ],
     },
-    a11y: {
-      config: {
-        rules: [
-          {
-            id: 'color-contrast', // false positive from animate in on the breadcrumbs
-            enabled: false,
-          },
-          {
-            id: 'landmark-unique', // false positive from having multiple TitleBlocks on a page
-            enabled: false,
-          },
-        ],
-      },
-    },
   },
   render: (args) => (
     <StickerSheet>
@@ -739,6 +733,34 @@ export const WithOnlySecondaryActions: Story = {
   },
 }
 
+export const WithDefaultActionBadge: Story = {
+  parameters: {
+    viewport: viewports,
+    chromatic: { disable: true },
+  },
+  args: {
+    variant: 'light',
+    title: 'Goals',
+    surveyStatus: undefined,
+    avatar: undefined,
+    breadcrumb: undefined,
+    secondaryActions: undefined,
+    secondaryOverflowMenuItems: undefined,
+    // Badge is supported: it passes through to the underlying button.
+    defaultAction: {
+      label: 'View drafts',
+      href: '#',
+      badge: { text: '3' },
+    },
+    // Only the primary action can be a menu group (label + menuItems).
+    primaryAction: {
+      label: 'Create goal',
+      menuItems: [{ label: 'Create a single goal' }, { label: 'Bulk create goals' }],
+    },
+    navigationTabs: LIGHT_NAVIGATION_TABS,
+  },
+}
+
 export const StickyTopStripInScrollableContainer: Story = {
   name: 'Sticker Sheet (Sticky Top Strip In Scrollable Container)',
   parameters: {

package/src/TitleBlock/types.ts

@@ -17,6 +17,11 @@ import { type NavigationTabProps } from './subcomponents/NavigationTabs'
 export type TitleBlockProps = {
   children?: React.ReactNode
   title: string
+  /**
+   * `light` is the recommended variant for new implementations. Leaving `variant`
+   * unset falls back to the default purple background.
+   *
+   */
   variant?: TitleBlockVariant
   breadcrumb?: TitleBlockBreadcrumbType
   avatar?: JSX.Element | TitleBlockAvatarProps