@uniweb/theming 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/theming",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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
 }

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: {
@@ -369,6 +378,49 @@ export function validateThemeConfig(config) {
   }
 }
 
+/**
+ * Merge inline text styles over the framework defaults, property by property.
+ *
+ * Everything else in theme.yml merges at the granularity of the leaf value —
+ * `contexts[name]` merges your tokens into the default context object, `colors`
+ * and `appearance` merge per key. This does the same one level down, so a site
+ * declares only the deltas:
+ *
+ *   inline:
+ *     accent:
+ *       font-weight: inherit    # keeps the default colour
+ *
+ * A shallow merge replaced the whole style object instead, so the example above
+ * silently produced `span[accent] { font-weight: inherit }` with no colour at
+ * all, and accented text rendered in the surrounding heading colour. The failure
+ * was subtractive and invisible in the config — you had to know what the default
+ * contained to notice it was gone. Three of the shipped templates carried a
+ * verbatim restatement of the default `accent` style purely to work around this.
+ *
+ * To *drop* a default property rather than change it, give it a neutral CSS
+ * value — `font-weight: inherit` to follow the surrounding text, or `initial` /
+ * `unset` / `revert`. Setting a whole style to null still removes it entirely
+ * (the CSS generator skips non-object entries).
+ *
+ * @param {Object} defaults - DEFAULT_INLINE
+ * @param {Object} [overrides] - rawConfig.inline
+ * @returns {Object} merged style map
+ */
+function mergeInlineStyles(defaults, overrides) {
+  const merged = { ...defaults }
+
+  for (const [name, style] of Object.entries(overrides || {})) {
+    // Non-objects (null/false) pass through so a site can delete a default
+    // style outright; anything else layers over the default of the same name.
+    merged[name] =
+      style && typeof style === 'object' && !Array.isArray(style)
+        ? { ...(defaults[name] || {}), ...style }
+        : style
+  }
+
+  return merged
+}
+
 /**
  * Normalize appearance configuration
  *
@@ -486,6 +538,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 })) {
@@ -637,8 +702,7 @@ export function processTheme(rawConfig = {}, options = {}) {
   const background = rawConfig.background || null
 
   // Inline text styles (semantic names → CSS declarations)
-  // Merge framework defaults with user overrides (user values win)
-  const inline = { ...DEFAULT_INLINE, ...(rawConfig.inline || {}) }
+  const inline = mergeInlineStyles(DEFAULT_INLINE, rawConfig.inline)
 
   const config = {
     colors,      // Raw colors for CSS generator