@keenmate/pure-admin-core 2.4.0 → 2.5.0

package/snippets/typography.html

@@ -1,9 +1,65 @@
-<!-- Typography Component (.pa-text)
-     BEM pattern for paragraph text styling
-     ================================================== -->
+<!-- ================================
+     TYPOGRAPHY
+     Pure Admin Visual Framework
+     ================================ -->
+
+<!--
+FOUNDATION — 10px rem base
+The framework sets html { font-size: 10px } so rem maths is trivial:
+  1rem  = 10px    1.4rem = 14px   1.6rem = 16px   2rem = 20px
+Body text is 1.6rem (16px) by default. Every pa-text size below reads
+off the same `$font-size-*` scale.
+-->
+
+
+<!-- ================================
+     BASE ELEMENTS (no class needed)
+     _base.scss applies framework-wide defaults to raw tags so a fresh
+     page using pa-admin looks right with zero markup noise.
+     ================================ -->
+
+<!-- Heading margins/padding are set via $heading-margin-top/bottom -->
+<h1>Heading 1</h1>
+<h2>Heading 2</h2>
+<h3>Heading 3</h3>
+<h4>Heading 4</h4>
+
+<!-- Paragraph spacing via $paragraph-margin-top/bottom -->
+<p>A paragraph of body text. Default font-family and colour flow from
+the active theme (<code>var(--base-font-family)</code>, <code>var(--pa-text-color-1)</code>).</p>
+
+<!-- Lists use padding-inline-start so bullets sit on the correct side in RTL -->
+<ul>
+  <li>Ordered and unordered lists get framework margins + a logical
+      inline-start padding so they mirror correctly in RTL.</li>
+  <li>Add <code>class="unstyled"</code> on <code>&lt;ul&gt;</code>/<code>&lt;ol&gt;</code>
+      to remove bullets and padding (for nav / button lists).</li>
+</ul>
+
+<!-- Definition list -->
+<dl>
+  <dt>Term</dt>
+  <dd>Description of the term.</dd>
+</dl>
+
+<!-- Blockquote uses padding-inline-start too -->
+<blockquote>A blockquote sits indented on the reading-start side.</blockquote>
+
+<!-- Horizontal rule gets framework margins -->
+<hr>
+
+<!-- pre: overflow-x: auto by default so long lines scroll instead of breaking the page -->
+<pre>Preformatted text block.</pre>
 
-<!-- Base Text (default: 14px, primary color) -->
-<p class="pa-text">Default paragraph text with 14px font size and primary color.</p>
+
+<!-- ================================
+     .pa-text — paragraph typography component
+     The canonical way to apply framework text styles to a block.
+     Works on <p>, <span>, <div> — any element.
+     ================================ -->
+
+<!-- Base (default: 14px, primary text colour) -->
+<p class="pa-text">Default paragraph text with 14px font size and primary colour.</p>
 
 <!-- Size Modifiers -->
 <p class="pa-text pa-text--xs">Extra small text (10px)</p>
@@ -12,40 +68,63 @@
 <p class="pa-text pa-text--lg">Large text (16px)</p>
 <p class="pa-text pa-text--xl">Extra large text (18px)</p>
 
-<!-- Color Modifiers -->
-<p class="pa-text pa-text--primary">Primary color text</p>
-<p class="pa-text pa-text--secondary">Secondary/muted color text</p>
+<!-- Colour Modifiers -->
+<p class="pa-text pa-text--primary">Primary colour text (= default, maps to --pa-text-color-1)</p>
+<p class="pa-text pa-text--secondary">Secondary/muted colour text (--pa-text-color-2)</p>
 
-<!-- Alignment Modifiers -->
-<p class="pa-text pa-text--start">Start aligned text</p>
-<p class="pa-text pa-text--center">Center aligned text</p>
-<p class="pa-text pa-text--end">End aligned text</p>
+<!-- Alignment Modifiers (logical — mirror in RTL) -->
+<p class="pa-text pa-text--start">Start-aligned text  (left in LTR, right in RTL)</p>
+<p class="pa-text pa-text--center">Center-aligned text</p>
+<p class="pa-text pa-text--end">End-aligned text    (right in LTR, left in RTL)</p>
 
-<!-- Semantic Variants -->
+<!-- Semantic Variants (compound styles) -->
 
-<!-- Caption: Small secondary text with bottom margin (for hints/descriptions) -->
-<p class="pa-text pa-text--caption">This is a caption - small, secondary, with margin-bottom</p>
+<!-- Caption: small + secondary + margin-bottom — ideal above a component as a hint -->
+<p class="pa-text pa-text--caption">29 badges in narrow container</p>
 
-<!-- Lead: Larger intro text with relaxed line height -->
-<p class="pa-text pa-text--lead">This is lead text - larger font with relaxed line height for introductory paragraphs.</p>
+<!-- Lead: larger + relaxed line-height — ideal for intro paragraphs -->
+<p class="pa-text pa-text--lead">Lead text — larger font with relaxed line height for introductory paragraphs.</p>
 
 <!-- Combined Modifiers -->
 <p class="pa-text pa-text--sm pa-text--secondary">Small secondary text</p>
-<p class="pa-text pa-text--lg pa-text--center">Large centered text</p>
+<p class="pa-text pa-text--lg pa-text--center">Large centred text</p>
 <p class="pa-text pa-text--xs pa-text--end pa-text--secondary">Extra small, end-aligned, secondary</p>
 
-<!-- With Spacing Utilities -->
-<p class="pa-text pa-text--secondary mt-4">Secondary text with top margin</p>
-<p class="pa-text pa-text--caption mb-6">Caption with larger bottom margin</p>
 
-<!-- Practical Examples -->
+<!-- ================================
+     FONT FAMILY SWITCHERS (_fonts.scss)
+     ================================ -->
 
-<!-- Demo/hint text above a component -->
-<h4>Badge Wrapping Demo</h4>
-<p class="pa-text pa-text--caption">29 badges in narrow container</p>
-<div class="pa-badge-group"><!-- badges here --></div>
+<p class="font-family-system">System font stack (native UI feel)</p>
+<p class="font-family-sans">Sans-serif stack</p>
+<p class="font-family-serif">Serif stack</p>
+<p class="font-family-mono">Monospace stack (same font as &lt;code&gt;)</p>
+
+
+<!-- ================================
+     SEMANTIC TEXT COLOURS (utilities.scss)
+     Use these when you want a *colour* without the rest of pa-text's
+     baseline sizing. They apply with !important so they win over
+     component-scoped colour rules.
+     ================================ -->
 
-<!-- Card header description -->
+<span class="text-primary">Primary (accent)</span>
+<span class="text-success">Success (green)</span>
+<span class="text-danger">Danger (red)</span>
+<span class="text-warning">Warning (yellow/orange)</span>
+<span class="text-info">Info (cyan/blue)</span>
+
+<!-- Theme colour slots 1..9 -->
+<span class="text-color-1">Theme colour 1</span>
+<span class="text-color-2">Theme colour 2</span>
+<!-- Pattern: text-color-{1..9} -->
+
+
+<!-- ================================
+     PRACTICAL EXAMPLES
+     ================================ -->
+
+<!-- Card header with secondary description -->
 <div class="pa-card__header">
     <h3>Feature Title</h3>
     <p class="pa-text pa-text--secondary">Brief description of this feature or section.</p>
@@ -58,44 +137,90 @@
     </p>
 </div>
 
-<!-- Centered tab content -->
+<!-- Centred tab panel copy -->
 <div class="pa-tabs__panel">
     <p class="pa-text pa-text--center">Feature highlights and capabilities.</p>
 </div>
 
 <!-- Toast/notification helper -->
 <p class="pa-text pa-text--secondary mt-4">
-    Progress bar shows time remaining before auto-dismiss (5 seconds)
+    Progress bar shows time remaining before auto-dismiss (5 seconds).
 </p>
 
+
+<!-- ================================
+     COMPONENT REFERENCE
+     ================================ -->
+
 <!--
-Available Classes Reference:
-============================
-
-Base:
-  .pa-text                    Default (14px, primary color)
-
-Sizes:
-  .pa-text--xs                10px (extra small)
-  .pa-text--sm                12px (small)
-  .pa-text--lg                16px (large)
-  .pa-text--xl                18px (extra large)
-
-Colors:
-  .pa-text--primary           Primary text color
-  .pa-text--secondary         Secondary/muted text color
-
-Alignment:
-  .pa-text--start              Start align
-  .pa-text--center            Center align
-  .pa-text--end             End align
-
-Semantic:
-  .pa-text--caption           Small + secondary + margin-bottom (for hints)
-  .pa-text--lead              Large + relaxed line-height (for intros)
-
-Combine with spacing utilities:
-  mt-1 through mt-20          Margin top
-  mb-1 through mb-20          Margin bottom
-  (see utilities.scss for full spacing scale)
+REM BASE:
+  html { font-size: 10px } — every 1rem is 10px, so pixel-to-rem conversions are trivial.
+  body default text: 1.6rem = 16px.
+
+FONT-SIZE SCALE (SCSS variables, all relative to the 10px rem base):
+  $font-size-2xs   1rem   10px
+  $font-size-xs    1.2rem 12px
+  $font-size-sm    1.4rem 14px   ← pa-text default
+  $font-size-md    1.5rem 15px
+  $font-size-base  1.6rem 16px   ← body default
+  $font-size-lg    1.8rem 18px
+  $font-size-xl    2rem   20px
+  $font-size-2xl   2.4rem 24px
+
+BASE ELEMENTS (from _base.scss, apply automatically):
+  h1..h6        $heading-margin-top / $heading-margin-bottom
+  p             $paragraph-margin-top / $paragraph-margin-bottom
+  ul, ol        padding-inline-start: $list-padding-left (RTL-aware)
+  ul.unstyled   bullets + padding removed (for nav / button lists)
+  dl, dd        list margins + 0 padding
+  blockquote    padding-inline-start: $blockquote-padding-left
+  hr            $hr-margin-top / $hr-margin-bottom
+  figure        $figure-margin-top / $figure-margin-bottom
+  pre           overflow-x: auto
+  button, input, select, textarea, label
+                font-family: inherit; font-size: inherit — so form
+                controls track the theme font instead of OS defaults.
+
+.pa-text — BEM paragraph component (from _utilities.scss):
+  Base       .pa-text            (14px, --pa-text-color-1)
+
+  Sizes      .pa-text--xs        10px
+             .pa-text--sm        12px
+             .pa-text--lg        16px
+             .pa-text--xl        18px
+
+  Colours    .pa-text--primary   --pa-text-color-1   (same as default)
+             .pa-text--secondary --pa-text-color-2   (muted)
+
+  Alignment  .pa-text--start     text-align: start   (RTL-aware)
+             .pa-text--center    text-align: center
+             .pa-text--end       text-align: end     (RTL-aware)
+
+  Semantic   .pa-text--caption   12px + secondary + margin-bottom: $spacing-sm
+                                  → small hint/description above a component
+             .pa-text--lead      16px + $line-height-relaxed
+                                  → intro paragraph
+
+FONT FAMILY SWITCHERS (_fonts.scss):
+  .font-family-system   native OS font stack
+  .font-family-sans     sans-serif stack
+  .font-family-serif    serif stack
+  .font-family-mono     monospace stack (same as <code>)
+
+SEMANTIC TEXT COLOURS (_utilities.scss — !important, colour-only):
+  .text-primary / -success / -danger / -warning / -info
+  .text-color-{1..9}                theme palette slots
+  .text-muted                       synonym for --pa-text-color-2
+  (Use pa-text--primary/--secondary when you want sizing + colour;
+   use .text-* when you just want colour.)
+
+TEXT UTILITIES (_utilities.scss):
+  .text-center        synonym for pa-text--center without the rest of pa-text
+  .text-nowrap        white-space: nowrap
+  .text-truncate      overflow hidden + ellipsis + nowrap
+
+COMBINE WITH SPACING UTILITIES:
+  .mt-1 .. .mt-20     margin-top
+  .mb-1 .. .mb-20     margin-bottom
+  (see utilities.scss for full spacing scale + semantic sizes like mt-md)
 -->