@fpkit/acss 3.1.0 → 3.2.0

package/src/sass/GLOBALS-STYLES.md

@@ -0,0 +1,631 @@
+# Global Styles Documentation
+
+Typography and layout styling with CSS custom properties for @fpkit/acss.
+
+## Overview
+
+Global styles provide baseline typography, layout, and semantic HTML element styling across your application. All styles use:
+
+- **Rem units** for responsive sizing (1rem = 16px default)
+- **Logical properties** for internationalization (`padding-inline`, `margin-block`)
+- **CSS custom properties** for complete customization
+- **Semantic naming** following project conventions
+
+---
+
+## Table of Contents
+
+- [Typography](#typography)
+  - [Horizontal Rule (HR)](#horizontal-rule-hr)
+  - [Blockquote](#blockquote)
+  - [Headings](#headings)
+  - [Paragraphs](#paragraphs)
+  - [Lists](#lists)
+- [Layout](#layout)
+  - [Body](#body)
+  - [Sections](#sections)
+  - [Skip Links](#skip-links)
+- [Utility Variables](#utility-variables)
+- [Best Practices](#best-practices)
+
+---
+
+## Typography
+
+### Horizontal Rule (HR)
+
+Horizontal rules for content dividers.
+
+#### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--hr-border-width` | `0.0625rem` | Line thickness (1px) |
+| `--hr-border-style` | `solid` | Line style (`solid`, `dashed`, `dotted`) |
+| `--hr-border-color` | `var(--color-border-subtle, #d3d3d3)` | Line color (uses global theme) |
+| `--hr-margin-block` | `1.5rem` | Vertical spacing above and below |
+
+#### Default Styles
+
+```css
+hr {
+  --hr-border-width: 0.0625rem;
+  --hr-border-style: solid;
+  --hr-border-color: var(--color-border-subtle, #d3d3d3);
+  --hr-margin-block: 1.5rem;
+
+  border: none;
+  border-bottom: var(--hr-border-width) var(--hr-border-style) var(--hr-border-color);
+  margin-block: var(--hr-margin-block);
+  display: block;
+  min-width: 100%;
+}
+```
+
+#### Customization Examples
+
+**Thicker HR:**
+```css
+hr.thick {
+  --hr-border-width: 0.125rem; /* 2px */
+  --hr-border-color: #000000;
+}
+```
+
+**Dashed Divider:**
+```css
+hr.dashed {
+  --hr-border-style: dashed;
+}
+```
+
+**Minimal HR with Extra Spacing:**
+```css
+hr.minimal {
+  --hr-border-width: 0.0625rem;
+  --hr-border-color: var(--color-border-subtle);
+  --hr-margin-block: 3rem;
+}
+```
+
+**Accent HR:**
+```css
+hr.accent {
+  --hr-border-width: 0.1875rem; /* 3px */
+  --hr-border-color: #667eea;
+  --hr-margin-block: 2rem;
+}
+```
+
+---
+
+### Blockquote
+
+Styled quotations with left border accent.
+
+#### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--blockquote-padding` | `1rem` | Internal padding |
+| `--blockquote-border-width` | `0.3125rem` | Left border width (5px) |
+| `--blockquote-border-style` | `solid` | Border style |
+| `--blockquote-border-color` | `var(--color-border, #d3d3d3)` | Border color (uses global theme) |
+
+#### Default Styles
+
+```css
+blockquote {
+  --blockquote-padding: 1rem;
+  --blockquote-border-width: 0.3125rem;
+  --blockquote-border-style: solid;
+  --blockquote-border-color: var(--color-border, #d3d3d3);
+
+  padding: var(--blockquote-padding);
+  border-left: var(--blockquote-border-width) var(--blockquote-border-style) var(--blockquote-border-color);
+}
+```
+
+#### Customization Examples
+
+**Thick Accent Blockquote:**
+```css
+blockquote.accent {
+  --blockquote-border-width: 0.5rem; /* 8px */
+  --blockquote-border-color: #667eea;
+  --blockquote-padding: 1.5rem;
+}
+```
+
+**Minimal Blockquote:**
+```css
+blockquote.minimal {
+  --blockquote-border-width: 0.125rem; /* 2px */
+  --blockquote-border-color: var(--color-border-subtle);
+  --blockquote-padding: 0.75rem;
+}
+```
+
+**Dashed Border:**
+```css
+blockquote.dashed {
+  --blockquote-border-style: dashed;
+  --blockquote-border-width: 0.1875rem; /* 3px */
+}
+```
+
+**Callout Box:**
+```css
+blockquote.callout {
+  --blockquote-padding: 1.5rem;
+  --blockquote-border-width: 0.25rem;
+  --blockquote-border-color: #ffc107;
+  background-color: #fff3cd;
+  border-radius: 0.25rem;
+}
+```
+
+---
+
+### Headings
+
+Semantic heading styles (h1-h6).
+
+#### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--fs-weight` | `500` | Font weight for headings and strong text |
+
+#### Default Styles
+
+```css
+h1, h2, h3, h4, h5, h6 {
+  font-weight: var(--fs-weight);
+  margin-block-start: 0;
+  margin-block-end: 1rem;
+  line-height: 1.2;
+}
+```
+
+#### Customization
+
+```css
+/* Bolder headings */
+:root {
+  --fs-weight: 700;
+}
+
+/* Individual heading styles */
+h1 {
+  font-size: 2.5rem;
+  --fs-weight: 800;
+}
+
+h2 {
+  font-size: 2rem;
+  --fs-weight: 700;
+}
+```
+
+---
+
+### Paragraphs
+
+Default paragraph styling with optimal line length.
+
+#### Default Styles
+
+```css
+p {
+  max-width: 75ch; /* Optimal reading width */
+  font-size: var(--fs-0); /* Base font size */
+  line-height: 1.6; /* Comfortable reading */
+}
+
+p + p {
+  margin-block-start: 1rem; /* Spacing between paragraphs */
+}
+```
+
+#### Customization
+
+```css
+/* Wide paragraphs */
+p.wide {
+  max-width: 100ch;
+}
+
+/* Narrow paragraphs */
+p.narrow {
+  max-width: 60ch;
+}
+
+/* Tight spacing */
+p.tight + p.tight {
+  margin-block-start: 0.5rem;
+}
+
+/* Loose spacing */
+p.loose + p.loose {
+  margin-block-start: 2rem;
+}
+```
+
+---
+
+### Lists
+
+Flexible list styling with CSS custom properties.
+
+#### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--li-display` | `flex` | Display mode for lists |
+| `--li-direction` | `column` | Flex direction |
+| `--li-gap` | `0.2rem` | Gap between list items |
+| `--li-wrap` | `nowrap` | Flex wrap behavior |
+| `--li-ps` | `var(--spc-3)` | Padding start (left padding) |
+| `--li-style` | `none` | List style for unstyled lists |
+
+#### Default Styles
+
+```css
+ul, ol {
+  display: var(--li-display, flex);
+  flex-direction: var(--li-direction, column);
+  gap: var(--li-gap, 0.2rem);
+  flex-wrap: var(--li-wrap, nowrap);
+  padding-inline-start: var(--li-ps, var(--spc-3));
+}
+
+/* Unstyled lists */
+[role="list"],
+[data-list~="unstyled"] {
+  list-style: var(--li-style, none);
+  margin-block-end: var(--li-my, 0);
+  margin-block-start: var(--li-mx, 0);
+}
+
+/* Inline lists */
+[data-list~="inline"] {
+  --li-direction: row;
+  --li-gap: 1rem;
+  --li-wrap: wrap;
+  --li-px: 0;
+  --li-pi: 0;
+}
+```
+
+#### Examples
+
+**Inline Navigation:**
+```html
+<ul data-list="unstyled inline">
+  <li><a href="/">Home</a></li>
+  <li><a href="/about">About</a></li>
+  <li><a href="/contact">Contact</a></li>
+</ul>
+```
+
+**Spaced List:**
+```css
+ul.spaced {
+  --li-gap: 1rem;
+}
+```
+
+**Compact List:**
+```css
+ul.compact {
+  --li-gap: 0.1rem;
+}
+```
+
+---
+
+## Layout
+
+### Body
+
+Root body layout configuration.
+
+#### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--body-display` | `flex` | Display mode |
+| `--body-direction` | `column` | Flex direction |
+
+#### Default Styles
+
+```css
+body {
+  display: var(--body-display, flex);
+  min-height: 100%;
+  flex-direction: var(--body-direction, column);
+  min-width: 20.3125rem; /* 325px minimum */
+  font-size: var(--fs-0);
+}
+
+main {
+  flex-grow: 1; /* Main content fills available space */
+}
+```
+
+---
+
+### Sections
+
+Semantic section spacing.
+
+#### CSS Variables
+
+| Variable | Description |
+|----------|-------------|
+| `--sect-y` | Horizontal margin (inline) |
+| `--sect-x` | Vertical padding (block) |
+
+#### Default Styles
+
+```css
+section:not(nav) {
+  margin-inline: var(--sect-y, auto);
+  padding-block: var(--sect-x, --spc-4);
+}
+```
+
+---
+
+### Skip Links
+
+Accessibility feature for keyboard navigation.
+
+#### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--color-skip-link-bg` | `#f5f5f5` | Background color when focused |
+
+#### Default Styles
+
+```css
+body > a[href^="#"] {
+  position: absolute;
+  top: -4rem;
+  left: 0;
+  width: 100%;
+  display: block;
+  justify-content: flex-start;
+  padding: 1rem;
+  z-index: 100;
+  transition: top 0.3s;
+  border-radius: 0;
+  background-color: var(--color-skip-link-bg, #f5f5f5);
+}
+
+body > a[href^="#"]:focus {
+  top: 0; /* Slides into view on focus */
+}
+```
+
+#### Usage
+
+```html
+<body>
+  <a href="#main-content">Skip to main content</a>
+  <!-- Page content -->
+  <main id="main-content">
+    <!-- Main content starts here -->
+  </main>
+</body>
+```
+
+---
+
+## Utility Variables
+
+### Boolean-Like Variables
+
+Special variables for conditional CSS logic.
+
+| Variable | Value | Purpose |
+|----------|-------|---------|
+| `--TRUE` | `initial` | Enables a CSS property |
+| `--FALSE` | ` ` (empty) | Disables a CSS property |
+
+#### Documentation
+
+```css
+/* Boolean-like utility variables for conditional CSS logic
+ * Usage: property: var(--condition, var(--TRUE)) value;
+ * --TRUE (initial) applies the value, --FALSE (empty) skips it
+ */
+:root {
+  --TRUE: initial;
+  --FALSE: ;
+}
+```
+
+#### Example Usage
+
+```css
+/* Conditional border */
+.element {
+  border: var(--enable-border, var(--FALSE)) 1px solid black;
+}
+
+/* Enable the border */
+.element.bordered {
+  --enable-border: var(--TRUE);
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Use Rem Units
+
+Convert all pixel values to rem for responsive scaling.
+
+```css
+/* ❌ Don't use pixels */
+hr {
+  --hr-border-width: 2px;
+  --hr-margin-block: 24px;
+}
+
+/* ✅ Use rem */
+hr {
+  --hr-border-width: 0.125rem; /* 2px ÷ 16 = 0.125rem */
+  --hr-margin-block: 1.5rem;   /* 24px ÷ 16 = 1.5rem */
+}
+```
+
+### 2. Use Logical Properties
+
+Support internationalization with logical properties.
+
+```css
+/* ❌ Physical properties */
+margin-left: 1rem;
+margin-right: 1rem;
+margin-top: 2rem;
+margin-bottom: 2rem;
+
+/* ✅ Logical properties */
+margin-inline: 1rem;  /* Left/right in LTR, right/left in RTL */
+margin-block: 2rem;   /* Top/bottom */
+```
+
+### 3. Reference Global Theme Colors
+
+Use semantic color variables that cascade from global theme.
+
+```css
+/* ❌ Hard-coded colors */
+hr {
+  --hr-border-color: #d3d3d3;
+}
+
+/* ✅ Semantic theme colors */
+hr {
+  --hr-border-color: var(--color-border-subtle, #d3d3d3);
+}
+```
+
+### 4. Split Compound Properties
+
+Enable partial overrides with atomic properties.
+
+```css
+/* ❌ Shorthand property */
+--blockquote-border: 5px solid #d3d3d3;
+
+/* ✅ Atomic properties */
+--blockquote-border-width: 0.3125rem;
+--blockquote-border-style: solid;
+--blockquote-border-color: var(--color-border, #d3d3d3);
+```
+
+---
+
+## Theming Examples
+
+### Dark Theme
+
+```css
+:root {
+  --color-border-subtle: #333333;
+  --color-border: #404040;
+  --color-skip-link-bg: #2d2d2d;
+}
+```
+
+### High Contrast Theme
+
+```css
+:root {
+  --hr-border-width: 0.125rem;
+  --hr-border-color: #000000;
+  --blockquote-border-width: 0.5rem;
+  --blockquote-border-color: #000000;
+  --fs-weight: 700;
+}
+```
+
+### Minimal Theme
+
+```css
+:root {
+  --hr-border-width: 0.0625rem;
+  --hr-border-color: var(--color-border-subtle);
+  --hr-margin-block: 3rem;
+  --blockquote-border-width: 0.125rem;
+}
+```
+
+---
+
+## Resources
+
+- **CSS Variables Reference** - See [CSS-VARIABLES.md](../../CSS-VARIABLES.md) for complete documentation
+- **Theme Examples** - See [theme-examples.css](../../theme-examples.css) for pre-built themes
+- **Card Styles** - See [components/cards/STYLES.mdx](../components/cards/STYLES.mdx) for card-specific variables
+
+---
+
+## Quick Reference
+
+### HR Variables
+
+```css
+--hr-border-width: 0.0625rem;
+--hr-border-style: solid;
+--hr-border-color: var(--color-border-subtle, #d3d3d3);
+--hr-margin-block: 1.5rem;
+```
+
+### Blockquote Variables
+
+```css
+--blockquote-padding: 1rem;
+--blockquote-border-width: 0.3125rem;
+--blockquote-border-style: solid;
+--blockquote-border-color: var(--color-border, #d3d3d3);
+```
+
+### Typography Variables
+
+```css
+--fs-weight: 500;
+```
+
+### Layout Variables
+
+```css
+--body-display: flex;
+--body-direction: column;
+```
+
+### Utility Variables
+
+```css
+--TRUE: initial;
+--FALSE: ;
+```
+
+---
+
+## Browser Support
+
+All global styles use modern CSS features:
+
+- ✅ **CSS Custom Properties** - All modern browsers (IE11 not supported)
+- ✅ **Logical Properties** (`padding-inline`, `margin-block`) - Chrome 87+, Firefox 66+, Safari 14.1+
+- ✅ **Flexbox** - All modern browsers
+- ✅ **`:focus-visible`** - Chrome 86+, Firefox 85+, Safari 15.4+
+
+For older browser support, fallback values ensure graceful degradation.