[epic][docs] Docs Overhaul

[markcaron]

Epic for the docs overhaul work in CY24.

Grouped and in priority order-ish (with some low hanging fruit mixed in):

DPO dependent

• [ ] Grid & layout
  • [ ] Discovery on grid, layout and spacing — 1429
  • [ ] Create grid, layout and spacing styles for design system — TBD
  • [ ] Update pages with better content design (e.g. column structure, etc.) — 1431
• [ ] Typography
  • [ ] Create typography and base styles for design system — 1432

Starting fresh

Gutting and cleaning the docs workflow and styling.

• [ ] CSS standardization (part DPO dependent)
  • [x] Gut/clean up CSS and create a CSS subsystem for the docs site — 1426
• [x] Template files standardization
  • [x] Switch NJK to WEBC for layout — 1428
  • [x] Clean up template files — 1427

Page/Feature improvements

• [ ] Updating/adding sections
  • [ ] About — 1446
  • [ ] Get started — 1176
  • [x] Accessibility — 309
  • [ ] Contributing — 1175
  • [x] Team Support / Help page — 1443
  • [ ] Theming / color palette — 1639
• [ ] Wayfinding improvements
  • [x] Table of Contents on pages (list of links at top for easy win) — 1433
  • [x] Discovery on Jump Links (outside layout) vs. TOC (at top of layout) — 1434
  • [ ] Side Nav element (new) — 1329
  • [ ] Categorization for components (e.g. containers, actions, visualization, etc.) — 1437
  • [ ] "Also Known As" (i.e. keywords) for helping users find elements (e.g. "tag" vs "label") — 1436
  • [ ] Next/Previous page links — 1438 + 1716
  • [ ] GitHub links
  • [x] Repo link in nav — 1440
  • [ ] Edit this page link on pages — 1441
  • [ ] Component source link — 1442
  • [x] Version number in masthead — 1485
• [ ] Elements pages visual improvements
  • [ ] All Elements page refresh — 1447
  • [x] Make Props/Attr/Etc as a table — 1448
  • [ ] Best practices (i.e. this/not this) improvements — 1449
  • [ ] Make Installation / CDN tabs look nicer — 1450
• [ ] Demo improvements
  • [ ] Build better Playground — 1452
  • [x] View full demo link — 1451
  • [ ] Finish Code Block extensions — 1091
    • [x] Design updates
    • [x] Add show more/code disclosure — comment in 1091
  • [x] Relocate Demo as own "tab" (i.e. playground w/ knobs) — 1453
  • [ ] Sample component as replacement on Overview playground (i.e. live component embedded in page)
  • [ ] View demo tab link
• [ ] Pattern pages improvements
  • [ ] Add pattern pages for certain elements
  • [ ] Pattern help component pages (link to pattern pages)
• [ ] Customization help
  • [ ] Discovery on how to provide clearer info on tokens, CSS vars and shadow parts
• [x] Component statuses
  • [x] Improve component status — 1268

Future state

• [ ] Search
  • [ ] Add site search
• [ ] Theme toggle
  • [ ] Discovery on user agent preference w/ page-level theming
  • [ ] Add page-level theming to design system
  • [ ] Add theme toggle to docs site

[markcaron]

@coreyvickery @marionnegp as promised, here are a handful of issues that needs design work first, while we get more direction from the DPO on the DPO dependent stuff.

Quick wins

• 1433

• 1440

• 1441

• 1442

Others

• High priority: #1091
• High priority: #1329

• 1434

• 1438

• 1449

• 1450

Plus, there's all the updating/adding pages & sections stuff we're already working on.

[mfwells]

Adding a link to the /demo page as well as /demo/variants would be extremely useful for all Elements. ie: https://ux.redhat.com/elements/card/demo/variants/