@uniweb/theming 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/theming",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Theming utilities for the Uniweb platform — shade generation, CSS generation, theme processing",
   "type": "module",
   "exports": {

package/src/css-generator.js

@@ -26,7 +26,12 @@ const DEFAULT_CONTEXT_TOKENS = {
     'ring': 'var(--primary-500)',
     'link': 'var(--primary-600)',
     'link-hover': 'var(--primary-700)',
-    'accent': 'var(--accent-600)',
+    // Shade 500 is the site's colour exactly as authored (the palette anchors
+    // the input there). `link` and `primary` sit at 600 because they carry the
+    // strict contrast burden — body-size links, and white text on a fill. An
+    // accent is decorative emphasis, usually at display size, so it keeps the
+    // brand colour unmuddied instead of paying for contrast it doesn't need.
+    'accent': 'var(--accent-500)',
     'primary': 'var(--primary-600)',
     'primary-foreground': 'white',
     'primary-hover': 'var(--primary-700)',
@@ -55,7 +60,7 @@ const DEFAULT_CONTEXT_TOKENS = {
     'ring': 'var(--primary-500)',
     'link': 'var(--primary-600)',
     'link-hover': 'var(--primary-700)',
-    'accent': 'var(--accent-600)',
+    'accent': 'var(--accent-500)', // exact brand — see the light context
     'primary': 'var(--primary-600)',
     'primary-foreground': 'white',
     'primary-hover': 'var(--primary-700)',
@@ -84,6 +89,11 @@ const DEFAULT_CONTEXT_TOKENS = {
     'ring': 'var(--primary-500)',
     'link': 'var(--primary-400)',
     'link-hover': 'var(--primary-300)',
+    // Stays lightened, unlike the light/medium contexts which use the exact
+    // brand at 500. Every text token here is lightened (body, subtle, link)
+    // because a mid-brand hue on a near-black surface often isn't legible —
+    // a navy or forest-green accent at 500 would effectively disappear. A site
+    // whose brand does read on dark can set `contexts.dark.accent` to it.
     'accent': 'var(--accent-400)',
     'primary': 'var(--primary-500)',
     'primary-foreground': 'white',
@@ -108,6 +118,8 @@ const DEFAULT_CONTEXT_TOKENS = {
 const DEFAULT_COLORS = {
   primary: '#3b82f6',   // Blue
   secondary: '#64748b', // Slate
+  // Last resort only. A site that names no accent inherits its primary (see
+  // processTheme) — this literal is reached solely when the primary is unusable.
   accent: '#8b5cf6',    // Purple
   neutral: '#78716c',   // Stone
 }
@@ -573,6 +585,14 @@ export function generateThemeCSS(config = {}, options = {}) {
   }
 
   // 6. Dark scheme support (if enabled, default is dark, or follows system preference)
+  //
+  // This guard decides whether the `.scheme-dark` rules physically exist. It is
+  // the CANONICAL "site reaches dark" predicate; the model-side copy that the
+  // runtime boot resolver and kit's useAppearance consume is hasDarkScheme() in
+  // @uniweb/core (theme.js). These MUST agree — a scheme applied with no
+  // matching CSS renders as a light page claiming to be dark. @uniweb/theming
+  // has no @uniweb/core dependency (it also runs server-side in the platform),
+  // so the predicate is duplicated here by necessity; keep the two in lockstep.
   if (appearance.allowToggle || appearance.default === 'dark' || appearance.default === 'system' || appearance.schemes?.includes('dark')) {
     sections.push(generateDarkSchemeCSS(appearance, contexts.dark, colorVars))
   }

package/src/processor.js

@@ -26,10 +26,19 @@ const NEUTRAL_PRESETS = {
 /**
  * Default inline text styles (content-author markdown: [text]{accent})
  * These reference semantic tokens so they adapt to context automatically
+ *
+ * `accent` resolves to --accent, not --link. It used to be --link, which
+ * conflated two roles that have genuinely different constraints: --link means
+ * "navigable text" and must stay readable at body size (4.5:1), while an accent
+ * is decorative emphasis, usually at display size (3:1 suffices). Welding them
+ * together meant a site that responsibly darkened its link colour also drained
+ * the brand colour out of its headlines, where the darker value buys nothing.
+ * It also left the `accent` colour family nearly unreachable from markdown, and
+ * contradicted `callout` right below, which already used --accent.
  */
 const DEFAULT_INLINE = {
   accent: {
-    color: 'var(--link)',
+    color: 'var(--accent)',
     'font-weight': '600',
   },
   callout: {
@@ -486,6 +495,19 @@ export function processTheme(rawConfig = {}, options = {}) {
     rawColors.neutral = NEUTRAL_PRESETS[rawColors.neutral]
   }
 
+  // A site that declares no accent colour almost always means "my brand
+  // colour" — an accent is an optional second voice, not a required one. The
+  // alternative is a fixed hue nobody chose showing up wherever markdown says
+  // [text]{accent} or {callout}. Falling back to primary also makes the
+  // --accent token safe to use as a default elsewhere: it is always *a* brand
+  // colour rather than a stock purple. The literal in DEFAULT_COLORS survives
+  // only as a last resort for a site whose primary is unusable.
+  const brandColor = rawColors.primary ?? defaultColors.primary
+  const isUsableColor = (v) => (typeof v === 'object' && v !== null) || isValidColor(v)
+  if (rawColors.accent === undefined && isUsableColor(brandColor)) {
+    rawColors.accent = brandColor
+  }
+
   // Filter to only valid colors (skip invalid ones in non-strict mode)
   const validColors = {}
   for (const [name, value] of Object.entries({ ...defaultColors, ...rawColors })) {