@fpkit/acss 3.1.1 → 3.2.0

package/src/components/list/STYLES.mdx

@@ -0,0 +1,631 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/List/Styles" />
+
+# List Styles
+
+Comprehensive list styling system with CSS custom properties for ul, ol, and dl
+elements with extensive variant support.
+
+## Overview
+
+The fpkit list styling system provides flexible, accessible list components for
+unordered (`<ul>`), ordered (`<ol>`), and definition (`<dl>`) lists. Includes
+automatic nested list styling, multiple variants, and comprehensive theming.
+
+### Key Features
+
+- **Three list types** - Unordered, ordered, and definition lists
+- **Nested list support** - Automatic marker changes for nested levels
+- **Five variants** - None, inline, custom, compact, and spaced
+- **Custom markers** - Full control over list markers via CSS variables
+- **Definition lists** - Styled `<dt>`/`<dd>` elements
+- **Print optimized** - Adjusted spacing for print media
+- **Accessibility** - Focus indicators and keyboard navigation support
+- **Rem-based sizing** - All measurements use rem units (1rem = 16px)
+
+## CSS Custom Properties
+
+### Base List Properties
+
+```css
+ul,
+ol,
+dl {
+  /* Spacing */
+  --list-margin-top: 0;
+  --list-margin-bottom: 1rem; /* 16px */
+  --list-margin-inline: 0;
+  --list-padding-inline: 0.5rem; /* 8px browser indent */
+  --list-gap: 0.5rem; /* 8px between items */
+
+  /* List Markers */
+  --list-marker-color: currentColor;
+  --list-marker-size: 1em; /* Relative to font size */
+  --list-marker-offset: 0.5rem; /* 8px space between marker and text */
+
+  /* Typography */
+  --list-font-size: 1rem; /* 16px */
+  --list-line-height: 1.5; /* 24px with 16px font */
+  --list-font-family: inherit;
+  --list-color: inherit;
+
+  /* List Item Spacing */
+  --list-item-margin-bottom: 0.5rem; /* 8px */
+  --list-item-padding-inline: 0;
+  --list-item-padding-block: 0;
+}
+```
+
+### Definition List Properties
+
+```css
+ul,
+ol,
+dl {
+  /* Definition Terms (dt) */
+  --dt-font-weight: 600; /* Semi-bold */
+  --dt-margin-bottom: 0.25rem; /* 4px */
+
+  /* Definition Descriptions (dd) */
+  --dd-margin-inline-start: 2rem; /* 32px indent */
+  --dd-margin-bottom: 1rem; /* 16px */
+}
+```
+
+### Custom Marker Properties
+
+```css
+[data-variant="custom"] li::before {
+  content: var(--list-marker-content, "•");
+}
+```
+
+## Unordered Lists (ul)
+
+### Basic Unordered List
+
+```html
+<ul>
+  <li>First item</li>
+  <li>Second item</li>
+  <li>Third item</li>
+</ul>
+```
+
+**CSS Applied:**
+
+```css
+ul {
+  list-style-type: disc;
+  padding-inline-start: 0.5rem;
+  margin-block-end: 1rem;
+}
+
+ul::marker {
+  color: currentColor;
+  font-size: 1em;
+}
+```
+
+### Nested Unordered Lists
+
+Automatic marker changes for nested levels:
+
+```html
+<ul>
+  <li>Level 1 (disc ●)</li>
+  <li>
+    Level 1
+    <ul>
+      <li>Level 2 (circle ○)</li>
+      <li>
+        Level 2
+        <ul>
+          <li>Level 3 (square ■)</li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+</ul>
+```
+
+**CSS:**
+
+```css
+ul {
+  list-style-type: disc;
+}
+ul ul {
+  list-style-type: circle;
+}
+ul ul ul {
+  list-style-type: square;
+}
+```
+
+## Ordered Lists (ol)
+
+### Basic Ordered List
+
+```html
+<ol>
+  <li>First step</li>
+  <li>Second step</li>
+  <li>Third step</li>
+</ol>
+```
+
+**CSS:**
+
+```css
+ol {
+  list-style-type: decimal;
+}
+```
+
+### Nested Ordered Lists
+
+Automatic numbering changes for nested levels:
+
+```html
+<ol>
+  <li>Step 1 (1, 2, 3...)</li>
+  <li>
+    Step 2
+    <ol>
+      <li>Substep 2.a (a, b, c...)</li>
+      <li>
+        Substep 2.b
+        <ol>
+          <li>Substep 2.b.i (i, ii, iii...)</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+</ol>
+```
+
+**CSS:**
+
+```css
+ol {
+  list-style-type: decimal;
+}
+ol ol {
+  list-style-type: lower-alpha;
+}
+ol ol ol {
+  list-style-type: lower-roman;
+}
+```
+
+## Definition Lists (dl)
+
+### Basic Definition List
+
+```html
+<dl>
+  <dt>Term 1</dt>
+  <dd>Definition for term 1.</dd>
+
+  <dt>Term 2</dt>
+  <dd>Definition for term 2.</dd>
+</dl>
+```
+
+**CSS:**
+
+```css
+dt {
+  font-weight: 600;
+  margin-block-end: 0.25rem;
+}
+
+dd {
+  margin-inline-start: 2rem; /* Indented */
+  margin-block-end: 1rem;
+}
+```
+
+### Multiple Definitions
+
+```html
+<dl>
+  <dt>Term</dt>
+  <dd>First definition</dd>
+  <dd>Second definition</dd>
+</dl>
+```
+
+## List Variants
+
+### None Variant
+
+Remove list styling:
+
+```html
+<ul data-variant="none">
+  <li>Item 1</li>
+  <li>Item 2</li>
+  <li>Item 3</li>
+</ul>
+```
+
+**CSS:**
+
+```css
+[data-variant="none"] {
+  list-style-type: none;
+  padding-inline-start: 0;
+}
+```
+
+### Inline Variant
+
+Horizontal list for navigation:
+
+```html
+<ul data-variant="inline">
+  <li><a href="/">Home</a></li>
+  <li><a href="/about">About</a></li>
+  <li><a href="/contact">Contact</a></li>
+</ul>
+```
+
+**CSS:**
+
+```css
+[data-variant="inline"] {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  padding-inline-start: 0;
+  list-style-type: none;
+}
+```
+
+### Custom Marker Variant
+
+Custom list markers using `::before`:
+
+```html
+<ul
+  data-variant="custom"
+  style="--list-marker-content: '✓'; --list-marker-color: green"
+>
+  <li>Completed task</li>
+  <li>Another task</li>
+</ul>
+```
+
+**CSS:**
+
+```css
+[data-variant="custom"] {
+  list-style-type: none;
+  padding-inline-start: 0;
+}
+
+[data-variant="custom"] li {
+  position: relative;
+  padding-inline-start: calc(
+    var(--list-marker-size) + var(--list-marker-offset)
+  );
+}
+
+[data-variant="custom"] li::before {
+  content: var(--list-marker-content, "•");
+  color: var(--list-marker-color);
+  font-size: var(--list-marker-size);
+  position: absolute;
+  left: 0;
+}
+```
+
+### Compact Variant
+
+Reduced spacing:
+
+```html
+<ul data-variant="compact">
+  <li>Compact item 1</li>
+  <li>Compact item 2</li>
+  <li>Compact item 3</li>
+</ul>
+```
+
+**CSS:**
+
+```css
+[data-variant="compact"] {
+  --list-gap: 0.25rem; /* 4px */
+  --list-item-margin-bottom: 0.25rem; /* 4px */
+  --list-margin-bottom: 0.5rem; /* 8px */
+}
+```
+
+### Spaced Variant
+
+Increased spacing:
+
+```html
+<ul data-variant="spaced">
+  <li>Spaced item 1</li>
+  <li>Spaced item 2</li>
+  <li>Spaced item 3</li>
+</ul>
+```
+
+**CSS:**
+
+```css
+[data-variant="spaced"] {
+  --list-gap: 1rem; /* 16px */
+  --list-item-margin-bottom: 1rem; /* 16px */
+}
+```
+
+## Real-World Examples
+
+### Navigation Menu
+
+```html
+<ul data-variant="inline" style="--list-gap: 2rem">
+  <li><a href="/">Home</a></li>
+  <li><a href="/products">Products</a></li>
+  <li><a href="/about">About</a></li>
+  <li><a href="/contact">Contact</a></li>
+</ul>
+```
+
+### Checklist with Custom Markers
+
+```html
+<ul
+  data-variant="custom"
+  style="--list-marker-content: '☐'; --list-marker-size: 1.2em"
+>
+  <li>Unchecked task</li>
+  <li style="--list-marker-content: '☑'; --list-marker-color: green">
+    Completed task
+  </li>
+  <li>Another task</li>
+</ul>
+```
+
+### Glossary (Definition List)
+
+```html
+<dl>
+  <dt>HTML</dt>
+  <dd>
+    HyperText Markup Language - the standard markup language for web pages.
+  </dd>
+
+  <dt>CSS</dt>
+  <dd>
+    Cascading Style Sheets - used for describing the presentation of a document.
+  </dd>
+
+  <dt>JavaScript</dt>
+  <dd>A programming language that enables interactive web pages.</dd>
+</dl>
+```
+
+### Step-by-Step Instructions
+
+```html
+<ol data-variant="spaced">
+  <li>
+    <strong>Step 1:</strong> Download the software
+    <ul>
+      <li>Visit the official website</li>
+      <li>Click the download button</li>
+    </ul>
+  </li>
+  <li>
+    <strong>Step 2:</strong> Install the application
+    <ul>
+      <li>Run the installer</li>
+      <li>Follow on-screen instructions</li>
+    </ul>
+  </li>
+  <li><strong>Step 3:</strong> Launch and configure</li>
+</ol>
+```
+
+### Feature List with Icons
+
+```html
+<ul
+  data-variant="custom"
+  style="--list-marker-content: '✨'; --list-marker-size: 1.5em"
+>
+  <li>Fast performance</li>
+  <li>Easy to use</li>
+  <li>Fully responsive</li>
+  <li>Accessible</li>
+</ul>
+```
+
+### Compact Footer Links
+
+```html
+<ul data-variant="inline compact">
+  <li><a href="/privacy">Privacy</a></li>
+  <li>|</li>
+  <li><a href="/terms">Terms</a></li>
+  <li>|</li>
+  <li><a href="/contact">Contact</a></li>
+</ul>
+```
+
+### Nested To-Do List
+
+```html
+<ul data-variant="custom" style="--list-marker-content: '☐'">
+  <li>
+    Project Planning
+    <ul data-variant="custom" style="--list-marker-content: '☐'">
+      <li style="--list-marker-content: '☑'; --list-marker-color: green">
+        Define scope
+      </li>
+      <li style="--list-marker-content: '☑'; --list-marker-color: green">
+        Set timeline
+      </li>
+      <li>Assign resources</li>
+    </ul>
+  </li>
+  <li>Development</li>
+  <li>Testing</li>
+</ul>
+```
+
+## Accessibility Considerations
+
+### Focus Indicators
+
+List items containing links or buttons get subtle focus treatment:
+
+```css
+li:has(a:focus-visible),
+li:has(button:focus-visible) {
+  outline: 0.0625rem solid transparent;
+}
+```
+
+### Semantic Structure
+
+Use appropriate list types:
+
+- **Unordered lists (`<ul>`)** - Related items without order
+- **Ordered lists (`<ol>`)** - Sequential steps or rankings
+- **Definition lists (`<dl>`)** - Term/definition pairs
+
+### Screen Reader Support
+
+Lists announce the number of items:
+
+```html
+<!-- Screen reader announces: "List, 3 items" -->
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+  <li>Item 3</li>
+</ul>
+```
+
+### Avoid Empty List Items
+
+```html
+<!-- Bad: Empty list item -->
+<ul>
+  <li></li>
+  <li>Item</li>
+</ul>
+
+<!-- Good: All items have content -->
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+```
+
+## Print Styles
+
+Lists automatically adjust for print:
+
+```css
+@media print {
+  ul,
+  ol,
+  dl {
+    --list-margin-bottom: 0.5rem;
+    --list-item-margin-bottom: 0.25rem;
+  }
+
+  ul,
+  ol {
+    list-style-position: inside; /* Keeps markers visible */
+  }
+}
+```
+
+## Reduced Motion
+
+Respects user's motion preferences:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ul,
+  ol,
+  dl,
+  li,
+  dt,
+  dd {
+    animation: none;
+    transition: none;
+  }
+}
+```
+
+## CSS Variable Naming Convention
+
+| Category         | Variable Pattern                     | Example                                        |
+| ---------------- | ------------------------------------ | ---------------------------------------------- |
+| **List Spacing** | `--list-{spacing-type}`              | `--list-margin-bottom`, `--list-gap`           |
+| **Markers**      | `--list-marker-{property}`           | `--list-marker-color`, `--list-marker-size`    |
+| **Typography**   | `--list-{property}`                  | `--list-font-size`, `--list-line-height`       |
+| **List Items**   | `--list-item-{property}`             | `--list-item-margin-bottom`                    |
+| **Definition**   | `--dt-{property}`, `--dd-{property}` | `--dt-font-weight`, `--dd-margin-inline-start` |
+
+## Browser Support
+
+- **CSS Custom Properties:** All modern browsers
+- **`::marker` pseudo-element:** Chrome 86+, Firefox 68+, Safari 11.1+
+- **`:has()` selector:** Chrome 105+, Firefox 121+, Safari 15.4+
+- **Logical properties:** Chrome 87+, Firefox 66+, Safari 14.1+
+- **Flexbox (inline variant):** All modern browsers
+
+## Performance Tips
+
+Create reusable list classes:
+
+```css
+.list-navigation {
+  --list-gap: 2rem;
+  --list-font-size: 1.125rem;
+}
+
+.list-compact {
+  --list-gap: 0.25rem;
+  --list-item-margin-bottom: 0.25rem;
+}
+```
+
+## Migration from Other Systems
+
+### From Tailwind CSS
+
+| Tailwind                 | fpkit List                                  |
+| ------------------------ | ------------------------------------------- |
+| `class="list-none"`      | `data-variant="none"`                       |
+| `class="list-disc"`      | Default `<ul>`                              |
+| `class="space-y-2"`      | `style="--list-item-margin-bottom: 0.5rem"` |
+| `class="flex space-x-4"` | `data-variant="inline"`                     |
+
+### From Bootstrap
+
+| Bootstrap               | fpkit List              |
+| ----------------------- | ----------------------- |
+| `class="list-unstyled"` | `data-variant="none"`   |
+| `class="list-inline"`   | `data-variant="inline"` |
+
+## Related Resources
+
+- **React Component** - See README for React List component API
+- **MDN: Lists** - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul
+- **W3C: List Structure** -
+  https://www.w3.org/WAI/tutorials/page-structure/content/