From f1cb1bf148e479b043a3c3438795041ea187144e Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:41:49 -0500
Subject: [PATCH 01/29] feat: add WithTransition type for per-value CSS
 transitions

Add core WithTransition module that enables property-specific transitions
rather than global transitions. Key features:

- WithTransition wrapper type pairs values with optional TransitionConfig
- AutoWrap typeclass for backwards compatibility with existing code
- Builder pattern: withTransition, withTiming, withDelay
- All-at-once function: withTransitionAll
- Rendering helpers: renderWithTransitionTW, compileWithTransitionTW
- Simplified TransitionConfig (no WhenTW) to avoid illegal nesting
- Preserved TransitionConfigGlobal for backwards compatibility

Transitions now apply to individual property values across screen sizes
and pseudo-classes (hover, focus, etc.) instead of globally.
---
 src/Classh/Box/Transition.hs |  59 +++++++++-----
 src/Classh/WithTransition.hs | 148 +++++++++++++++++++++++++++++++++++
 2 files changed, 187 insertions(+), 20 deletions(-)
 create mode 100644 src/Classh/WithTransition.hs

diff --git a/src/Classh/Box/Transition.hs b/src/Classh/Box/Transition.hs
index 6da4d8b..0accee6 100644
--- a/src/Classh/Box/Transition.hs
+++ b/src/Classh/Box/Transition.hs
@@ -58,7 +58,7 @@ data TransitionDuration
   | Duration_700
   | Duration_1000
   | Duration_Custom T.Text  -- ^ e.g., Duration_Custom "2000" for duration-[2000ms]
-  deriving Show
+  deriving (Show, Eq)
 
 -- | Transition timing function (easing)
 -- see https://v3.tailwindcss.com/docs/transition-timing-function
@@ -68,7 +68,7 @@ data TransitionTimingFunction
   | Ease_Out
   | Ease_InOut
   | Ease_Custom T.Text  -- ^ e.g., Ease_Custom "cubic-bezier(0.4,0,0.2,1)"
-  deriving Show
+  deriving (Show, Eq)
 
 -- | Transition delay
 -- see https://v3.tailwindcss.com/docs/transition-delay
@@ -83,19 +83,31 @@ data TransitionDelay
   | Delay_700
   | Delay_1000
   | Delay_Custom T.Text  -- ^ e.g., Delay_Custom "2000" for delay-[2000ms]
-  deriving Show
+  deriving (Show, Eq)
 
--- | Transition configuration
+-- | Transition configuration (simplified - no WhenTW!)
+-- When used with WithTransition, the transition property is inferred from context
+-- This prevents WhenTW nesting which cannot be rendered to valid CSS
 data TransitionConfig = TransitionConfig
-  { _transitionProperty :: WhenTW TransitionProperty
-  , _transitionDuration :: WhenTW TransitionDuration
-  , _transitionTiming :: WhenTW TransitionTimingFunction
-  , _transitionDelay :: WhenTW TransitionDelay
-  } deriving Show
+  { _transitionDuration :: TransitionDuration
+  , _transitionTiming :: TransitionTimingFunction
+  , _transitionDelay :: TransitionDelay
+  } deriving (Show, Eq)
 
 -- Template Haskell splice - must come after data type definitions
 makeLenses ''TransitionConfig
 
+-- | Legacy global transition config with WhenTW for backwards compatibility
+-- Used for the global _transition field in BoxConfig
+data TransitionConfigGlobal = TransitionConfigGlobal
+  { _transitionProperty :: WhenTW TransitionProperty
+  , _transitionDurationGlobal :: WhenTW TransitionDuration
+  , _transitionTimingGlobal :: WhenTW TransitionTimingFunction
+  , _transitionDelayGlobal :: WhenTW TransitionDelay
+  } deriving Show
+
+makeLenses ''TransitionConfigGlobal
+
 -- Instances for TransitionProperty
 instance Default TransitionProperty where
   def = Transition_None
@@ -135,22 +147,29 @@ instance ShowTW TransitionDelay where
     Delay_Custom val -> "delay-[" <> val <> "ms]"
     other -> "delay-" <> (T.drop 6 . tshow $ other)
 
--- Instances for TransitionConfig
+-- Instances for TransitionConfig (simplified, no WhenTW)
 instance Default TransitionConfig where
-  def = TransitionConfig def def def def
+  def = TransitionConfig def def def
+
+-- Note: TransitionConfig doesn't have ShowTW instance anymore
+-- It will be rendered contextually when used with WithTransition
+
+-- Instances for TransitionConfigGlobal (legacy)
+instance Default TransitionConfigGlobal where
+  def = TransitionConfigGlobal def def def def
 
-instance ShowTW TransitionConfig where
+instance ShowTW TransitionConfigGlobal where
   showTW cfg = foldr (<&>) mempty
     [ renderWhenTW (_transitionProperty cfg) showTW
-    , renderWhenTW (_transitionDuration cfg) showTW
-    , renderWhenTW (_transitionTiming cfg) showTW
-    , renderWhenTW (_transitionDelay cfg) showTW
+    , renderWhenTW (_transitionDurationGlobal cfg) showTW
+    , renderWhenTW (_transitionTimingGlobal cfg) showTW
+    , renderWhenTW (_transitionDelayGlobal cfg) showTW
     ]
 
-instance Semigroup TransitionConfig where
-  (<>) a b = TransitionConfig
+instance Semigroup TransitionConfigGlobal where
+  (<>) a b = TransitionConfigGlobal
     { _transitionProperty = _transitionProperty a <> _transitionProperty b
-    , _transitionDuration = _transitionDuration a <> _transitionDuration b
-    , _transitionTiming = _transitionTiming a <> _transitionTiming b
-    , _transitionDelay = _transitionDelay a <> _transitionDelay b
+    , _transitionDurationGlobal = _transitionDurationGlobal a <> _transitionDurationGlobal b
+    , _transitionTimingGlobal = _transitionTimingGlobal a <> _transitionTimingGlobal b
+    , _transitionDelayGlobal = _transitionDelayGlobal a <> _transitionDelayGlobal b
     }
diff --git a/src/Classh/WithTransition.hs b/src/Classh/WithTransition.hs
new file mode 100644
index 0000000..02115e4
--- /dev/null
+++ b/src/Classh/WithTransition.hs
@@ -0,0 +1,148 @@
+{-# LANGUAGE MultiParamTypeClasses #-}
+{-# LANGUAGE FlexibleInstances #-}
+{-# LANGUAGE UndecidableInstances #-}
+
+--------------------------------------------------------------------------------
+-- |
+--  Module      :  Classh.WithTransition
+--  Copyright   :  (c) 2024, Galen Sprout
+--  License     :  BSD-style (see end of this file)
+--
+--  Maintainer  :  Galen Sprout <galen.sprout@gmail.com>
+--  Stability   :  provisional
+--  Portability :  portable
+--
+--  Types to support CSS transitions bound to specific property values
+--
+--  Example use:
+--
+-- @
+--  -- Builder pattern
+--  bgColor .~^ [ ("def", purple)
+--              , ("hover", lavender `withTransition` Duration_300)
+--              , ("focus", indigo `withTransition` Duration_300 `withTiming` Ease_InOut)
+--              ]
+--
+--  -- All-at-once
+--  bgColor .~^ [ ("def", purple)
+--              , ("hover", lavender `withTransitionAll` Duration_300 Ease_InOut Delay_0)
+--              ]
+-- @
+--------------------------------------------------------------------------------
+
+module Classh.WithTransition where
+
+import Classh.Box.Transition
+import Classh.Class.ShowTW
+import Classh.Responsive.WhenTW
+import Classh.Internal.Chain
+import Data.Default
+import qualified Data.Text as T
+
+-- | Wraps a value with an optional transition configuration
+-- This allows transitions to be bound to specific property values
+data WithTransition a = WithTransition
+  { _wtValue :: a
+  , _wtTransition :: Maybe TransitionConfig
+  } deriving (Show, Eq)
+
+-- | Builder pattern: Start with duration, optionally chain timing/delay
+-- Example: lavender `withTransition` Duration_300 `withTiming` Ease_InOut
+withTransition :: a -> TransitionDuration -> WithTransition a
+withTransition val duration = WithTransition val (Just $ TransitionConfig
+  { _transitionDuration = duration
+  , _transitionTiming = def
+  , _transitionDelay = def
+  })
+
+-- | Builder: Add timing function to an existing WithTransition
+-- Example: ... `withTiming` Ease_InOut
+withTiming :: WithTransition a -> TransitionTimingFunction -> WithTransition a
+withTiming (WithTransition val Nothing) timing =
+  WithTransition val (Just $ TransitionConfig def timing def)
+withTiming (WithTransition val (Just cfg)) timing =
+  WithTransition val (Just $ cfg { _transitionTiming = timing })
+
+-- | Builder: Add delay to an existing WithTransition
+-- Example: ... `withDelay` Delay_100
+withDelay :: WithTransition a -> TransitionDelay -> WithTransition a
+withDelay (WithTransition val Nothing) delay =
+  WithTransition val (Just $ TransitionConfig def def delay)
+withDelay (WithTransition val (Just cfg)) delay =
+  WithTransition val (Just $ cfg { _transitionDelay = delay })
+
+-- | Create a value with all transition params at once
+-- Example: lavender `withTransitionAll` Duration_300 Ease_InOut Delay_100
+withTransitionAll :: a -> TransitionDuration -> TransitionTimingFunction -> TransitionDelay -> WithTransition a
+withTransitionAll val duration timing delay = WithTransition val (Just $ TransitionConfig duration timing delay)
+
+-- | Create a value with a pre-built transition config
+-- Example: lavender `withTransitionFull` myConfig
+withTransitionFull :: a -> TransitionConfig -> WithTransition a
+withTransitionFull val cfg = WithTransition val (Just cfg)
+
+-- | Create a value without a transition
+noTransition :: a -> WithTransition a
+noTransition val = WithTransition val Nothing
+
+-- | Type class for automatic wrapping in WithTransition
+-- This enables backwards compatibility for existing operators
+class AutoWrap a b where
+  autoWrap :: a -> b
+
+-- | Wrap plain values in WithTransition with Nothing
+-- This makes existing code work: bgColor .~~ purple
+instance AutoWrap a (WithTransition a) where
+  autoWrap a = WithTransition a Nothing
+
+-- | Pass through values that don't need wrapping
+-- This makes existing code work: colStart .~~ 2
+instance {-# OVERLAPPABLE #-} AutoWrap a a where
+  autoWrap = id
+
+-- | Pass through values that are already wrapped
+instance AutoWrap (WithTransition a) (WithTransition a) where
+  autoWrap = id
+
+instance Default a => Default (WithTransition a) where
+  def = WithTransition def Nothing
+
+instance Functor WithTransition where
+  fmap f (WithTransition val trans) = WithTransition (f val) trans
+
+-- | Helper for rendering WhenTW values wrapped in WithTransition
+-- Extracts the value, renders it with the provided function,
+-- and adds transition classes if a transition config is present
+renderWithTransitionTW :: WhenTW (WithTransition a)
+                       -> (a -> T.Text)
+                       -> TransitionProperty
+                       -> T.Text
+renderWithTransitionTW tws construct prop = foldr (<&>) mempty $
+  fmap (\(c, WithTransition val mTransCfg) ->
+    let prefix = if c == "def" then "" else (c <> ":")
+        valueClass = prefix <> construct val
+        transitionClasses = case mTransCfg of
+          Nothing -> mempty
+          Just cfg ->
+            let transProp = prefix <> showTW prop
+                transDur = prefix <> showTW (_transitionDuration cfg)
+                transTiming = prefix <> showTW (_transitionTiming cfg)
+                transDelay = prefix <> showTW (_transitionDelay cfg)
+            in transProp <&> transDur <&> transTiming <&> transDelay
+    in valueClass <&> transitionClasses
+  ) tws
+
+-- | Helper for compiling WithTransition values (with duplicate checking)
+compileWithTransitionTW :: WhenTW (WithTransition a)
+                        -> (a -> T.Text)
+                        -> TransitionProperty
+                        -> Either T.Text T.Text
+compileWithTransitionTW tws construct prop = case f $ fmap fst tws of
+  Left e -> Left e
+  Right () -> Right $ renderWithTransitionTW tws construct prop
+  where
+    f [] = Right ()
+    f (s:ss) =
+      if elem s ss
+      then Left $ s <> " exists twice"
+      else f ss

From 59d79181fb42b0a477e5f571c2bdc13d1a190803 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:42:21 -0500
Subject: [PATCH 02/29] feat: update BoxConfig background properties to use
 WithTransition

Update background color, opacity, and shadow to support per-value
transitions:

- _bgColor: WhenTW Color -> WhenTW (WithTransition Color)
- _bgOpacity: WhenTW Int -> WhenTW (WithTransition Int)
- _shadow: WhenTW BoxShadow -> WhenTW (WithTransition BoxShadow)
- _transition: TransitionConfig -> TransitionConfigGlobal

Remove local renderWithTransitionTW and compileWithTransitionTW
definitions in favor of importing from Classh.WithTransition module.

Update ShowTW and CompileStyle instances to use the new helpers with
proper TransitionProperty inference (Transition_Colors for colors,
Transition_Opacity for opacity, etc.).
---
 src/Classh/Box.hs | 82 +++++++++++++++++++++++------------------------
 1 file changed, 41 insertions(+), 41 deletions(-)

diff --git a/src/Classh/Box.hs b/src/Classh/Box.hs
index 3605241..22a041e 100644
--- a/src/Classh/Box.hs
+++ b/src/Classh/Box.hs
@@ -88,6 +88,7 @@ import Classh.Box.Placement as X
 import Classh.Box.Border as X
 import Classh.Box.Shadow as X
 import Classh.Box.Transition as X
+import Classh.WithTransition as X
 
 import Control.Lens hiding ((<&>))
 import Data.Default
@@ -96,15 +97,15 @@ import qualified Data.Text as T
 data BoxConfig = BoxConfig
   { _colStart :: WhenTW Int
   , _colSpan :: WhenTW Int
-  , _bgColor :: WhenTW Color
-  , _bgOpacity :: WhenTW Int -- 1 5 10 .. 100 -- def == 519
+  , _bgColor :: WhenTW (WithTransition Color)  -- Transitionable!
+  , _bgOpacity :: WhenTW (WithTransition Int)  -- Transitionable! (1 5 10 .. 100 -- def == 519)
   , _padding :: BoxPadding
   , _margin :: BoxMargin
   , _sizingBand :: BoxSizingBand
   , _border :: BorderConfig -- { rounded, thickness, etc .. }
   , _position :: WhenTW (Justify, Align)
-  , _shadow :: WhenTW BoxShadow
-  , _transition :: TransitionConfig
+  , _shadow :: WhenTW (WithTransition BoxShadow)  -- Transitionable!
+  , _transition :: TransitionConfigGlobal  -- Global transition (legacy support)
   --, _text_align :: Align ... or should we set == position.align
   , _box_custom :: T.Text
   }
@@ -113,7 +114,6 @@ data BoxConfig = BoxConfig
 
 makeLenses ''BoxConfig
 
-
 ------------  Defaults of Records
 
 instance Default BoxConfig where
@@ -130,10 +130,10 @@ instance CompileStyle BoxConfig where
       , compileSizingBand (_sizingBand cfg)
       , compilePadding (_padding cfg)
       , compileMargin (_margin cfg)
-      , compileWhenTW (_bgColor cfg) ((<>) "bg-" . showTW)
-      , compileWhenTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow)
-      , compileWhenTW (_shadow cfg) showTW
-      , compileTransition (_transition cfg)
+      , compileWithTransitionTW (_bgColor cfg) ((<>) "bg-" . showTW) Transition_Colors
+      , compileWithTransitionTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow) Transition_Opacity
+      , compileWithTransitionTW (_shadow cfg) showTW Transition_Shadow
+      , compileTransitionGlobal (_transition cfg)
       , Right $ _box_custom cfg
       ]
       where
@@ -147,54 +147,54 @@ instance CompileStyle BoxConfig where
           ]
 
         compileBorderRadius cfg' = pure . foldr (<&>) mempty =<< sequenceA
-          [ compileWhenTW (_borderRadius_tr cfg') ((<>) "rounded-tr" . showTW)
-          , compileWhenTW (_borderRadius_tl cfg') ((<>) "rounded-tl" . showTW)
-          , compileWhenTW (_borderRadius_br cfg') ((<>) "rounded-br" . showTW)
-          , compileWhenTW (_borderRadius_bl cfg') ((<>) "rounded-bl" . showTW)
+          [ compileWithTransitionTW (_borderRadius_tr cfg') ((<>) "rounded-tr" . showTW) Transition_All
+          , compileWithTransitionTW (_borderRadius_tl cfg') ((<>) "rounded-tl" . showTW) Transition_All
+          , compileWithTransitionTW (_borderRadius_br cfg') ((<>) "rounded-br" . showTW) Transition_All
+          , compileWithTransitionTW (_borderRadius_bl cfg') ((<>) "rounded-bl" . showTW) Transition_All
           ]
 
         compileBorderWidth cfg' = pure . foldr (<&>) mempty =<< sequenceA
-          [ compileWhenTW (_borderWidth_l cfg') ((<>) "border-l" . showTW)
-          , compileWhenTW (_borderWidth_r cfg') ((<>) "border-r" . showTW)
-          , compileWhenTW (_borderWidth_t cfg') ((<>) "border-t" . showTW)
-          , compileWhenTW (_borderWidth_b cfg') ((<>) "border-b" . showTW)
+          [ compileWithTransitionTW (_borderWidth_l cfg') ((<>) "border-l" . showTW) Transition_All
+          , compileWithTransitionTW (_borderWidth_r cfg') ((<>) "border-r" . showTW) Transition_All
+          , compileWithTransitionTW (_borderWidth_t cfg') ((<>) "border-t" . showTW) Transition_All
+          , compileWithTransitionTW (_borderWidth_b cfg') ((<>) "border-b" . showTW) Transition_All
           ]
 
         compileBorderColor cfg' = pure . foldr (<&>) mempty =<< sequenceA
-          [ compileWhenTW (_borderColor_l cfg') ((<>) "border-l-" . showTW)
-          , compileWhenTW (_borderColor_r cfg') ((<>) "border-r-" . showTW)
-          , compileWhenTW (_borderColor_t cfg') ((<>) "border-t-" . showTW)
-          , compileWhenTW (_borderColor_b cfg') ((<>) "border-b-" . showTW)
+          [ compileWithTransitionTW (_borderColor_l cfg') ((<>) "border-l-" . showTW) Transition_Colors
+          , compileWithTransitionTW (_borderColor_r cfg') ((<>) "border-r-" . showTW) Transition_Colors
+          , compileWithTransitionTW (_borderColor_t cfg') ((<>) "border-t-" . showTW) Transition_Colors
+          , compileWithTransitionTW (_borderColor_b cfg') ((<>) "border-b-" . showTW) Transition_Colors
           ]
 
         compileRing cfg' = pure . foldr (<&>) mempty =<< sequenceA
-          [ compileWhenTW (_ringWidth cfg') showTW
-          , compileWhenTW (_ringColor cfg') ((<>) "ring-" . showTW)
-          , compileWhenTW (_ringOpacity cfg') ((<>) "ring-opacity-" . tshow)
+          [ compileWithTransitionTW (_ringWidth cfg') showTW Transition_All
+          , compileWithTransitionTW (_ringColor cfg') ((<>) "ring-" . showTW) Transition_Colors
+          , compileWithTransitionTW (_ringOpacity cfg') ((<>) "ring-opacity-" . tshow) Transition_Opacity
           ]
 
         compileSizingBand cfg' = pure . foldr (<&>) mempty =<< sequenceA
-          [ compileWhenTW (_widthC . _maxSize $ cfg') ((<>) "max-w-" . showTW)
-          , compileWhenTW (_heightC . _maxSize $ cfg') ((<>) "max-h-" . showTW)
-          , compileWhenTW (_widthC . _minSize $ cfg') ((<>) "min-w-" . showTW)
-          , compileWhenTW (_heightC . _minSize $ cfg') ((<>) "min-h-" . showTW)
-          , compileWhenTW (_width . _size $ cfg') ((<>) "w-" . showTW)
-          , compileWhenTW (_height . _size $ cfg') ((<>) "h-" . showTW)
+          [ compileWithTransitionTW (_widthC . _maxSize $ cfg') ((<>) "max-w-" . showTW) Transition_All
+          , compileWithTransitionTW (_heightC . _maxSize $ cfg') ((<>) "max-h-" . showTW) Transition_All
+          , compileWithTransitionTW (_widthC . _minSize $ cfg') ((<>) "min-w-" . showTW) Transition_All
+          , compileWithTransitionTW (_heightC . _minSize $ cfg') ((<>) "min-h-" . showTW) Transition_All
+          , compileWithTransitionTW (_width . _size $ cfg') ((<>) "w-" . showTW) Transition_All
+          , compileWithTransitionTW (_height . _size $ cfg') ((<>) "h-" . showTW) Transition_All
           ]
 
 
         compileMargin cfg' = pure . foldr (<&>) mempty =<< sequenceA
-          [ compileWhenTW (_marginL cfg') ((<>) "ml-" . showTW)
-          , compileWhenTW (_marginR cfg') ((<>) "mr-" . showTW)
-          , compileWhenTW (_marginT cfg') ((<>) "mt-" . showTW)
-          , compileWhenTW (_marginB cfg') ((<>) "mb-" . showTW)
+          [ compileWithTransitionTW (_marginL cfg') ((<>) "ml-" . showTW) Transition_All
+          , compileWithTransitionTW (_marginR cfg') ((<>) "mr-" . showTW) Transition_All
+          , compileWithTransitionTW (_marginT cfg') ((<>) "mt-" . showTW) Transition_All
+          , compileWithTransitionTW (_marginB cfg') ((<>) "mb-" . showTW) Transition_All
           ]
 
-        compileTransition cfg' = pure . foldr (<&>) mempty =<< sequenceA
+        compileTransitionGlobal cfg' = pure . foldr (<&>) mempty =<< sequenceA
           [ compileWhenTW (_transitionProperty cfg') showTW
-          , compileWhenTW (_transitionDuration cfg') showTW
-          , compileWhenTW (_transitionTiming cfg') showTW
-          , compileWhenTW (_transitionDelay cfg') showTW
+          , compileWhenTW (_transitionDurationGlobal cfg') showTW
+          , compileWhenTW (_transitionTimingGlobal cfg') showTW
+          , compileWhenTW (_transitionDelayGlobal cfg') showTW
           ]
 
         compilePos posCfg = case f $ fmap fst posCfg of
@@ -217,8 +217,8 @@ instance ShowTW BoxConfig where
   showTW cfg = foldr (<&>) mempty
    [ renderWhenTW (_colStart cfg) ((<>) "col-start-" . tshow)
    , renderWhenTW (_colSpan cfg) ((<>) "col-span-" . tshow)
-   , renderWhenTW (_bgColor cfg) ((<>) "bg-" . showTW)
-   , renderWhenTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow)
+   , renderWithTransitionTW (_bgColor cfg) ((<>) "bg-" . showTW) Transition_Colors
+   , renderWithTransitionTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow) Transition_Opacity
    , showTW . _border $ cfg
    , showTW . _sizingBand $ cfg
    , showTW . _padding $ cfg
@@ -228,7 +228,7 @@ instance ShowTW BoxConfig where
         let prefix = if c == "def" then "" else (c <> ":")
         in prefix <> "grid" <&> prefix <> (showTW jus) <&> prefix <> (showTW align)
      ) $ _position cfg
-   , renderWhenTW (_shadow cfg) showTW
+   , renderWithTransitionTW (_shadow cfg) showTW Transition_Shadow
    , showTW . _transition $ cfg
    --, renderWhenTW (_position cfg) $ \(j,a) -> "grid " <> showTW j <> " " <> showTW a
    , _box_custom cfg

From d5ae5b20f31ae5b57189d3352e231f3036f62aa0 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:42:52 -0500
Subject: [PATCH 03/29] feat: update border properties to use WithTransition

Update all border properties to support per-value transitions:

Border Color (BorderColorSides):
- All fields: WhenTW Color -> WhenTW (WithTransition Color)
- Add FlexibleInstances pragma for SetSides instance

Border Width (BorderWidthSides):
- All fields: WhenTW BorderWidth -> WhenTW (WithTransition BorderWidth)
- Add FlexibleInstances pragma for SetSides instance

Border Radius (BorderRadiusCorners):
- All fields: WhenTW BorderRadius' -> WhenTW (WithTransition BorderRadius')
- Add FlexibleInstances pragma for SetSides instance

Remove local renderWithTransitionTW definitions, use centralized version
from Classh.WithTransition module.
---
 src/Classh/Box/Border/Color.hs  | 33 ++++++++++++++++++++-------------
 src/Classh/Box/Border/Radius.hs | 32 +++++++++++++++++++-------------
 src/Classh/Box/Border/Width.hs  | 30 ++++++++++++++++++------------
 3 files changed, 57 insertions(+), 38 deletions(-)

diff --git a/src/Classh/Box/Border/Color.hs b/src/Classh/Box/Border/Color.hs
index 4c79305..4363c68 100644
--- a/src/Classh/Box/Border/Color.hs
+++ b/src/Classh/Box/Border/Color.hs
@@ -1,3 +1,5 @@
+{-# LANGUAGE FlexibleInstances #-}
+
 module Classh.Box.Border.Color where
 
 import Classh.Class.ShowTW
@@ -5,26 +7,30 @@ import Classh.Class.SetSides
 import Classh.Responsive.WhenTW
 import Classh.Internal.Chain
 import Classh.Color
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 import Data.Default
 import Control.Lens (lens, makeLenses)
 
 
--- |Holds Border 'Color' by side
--- 
+-- |Holds Border 'Color' by side (transitionable)
+--
 --  For example:
--- 
+--
 -- > elClass "div" $(classh' [ border . bColor . borderColor_t .~~ Black ])
 -- > -- Or with shorthand
 -- > elClass "div" $(classh' [ bc_t .~~ Black ])
+-- > -- With transitions:
+-- > elClass "div" $(classh' [ bc_t .~^ [("def", Black), ("hover", Red `withTransition` Duration_300)] ])
 data BorderColorSides = BorderColorSides
-  { _borderColor_l :: WhenTW Color
+  { _borderColor_l :: WhenTW (WithTransition Color)
   -- ^ border-l-'Color' ... see https://tailwindcss.com/docs/border-color
-  , _borderColor_r :: WhenTW Color
+  , _borderColor_r :: WhenTW (WithTransition Color)
   -- ^ border-r-'Color' ... see https://tailwindcss.com/docs/border-color
-  , _borderColor_t :: WhenTW Color
+  , _borderColor_t :: WhenTW (WithTransition Color)
   -- ^ border-t-'Color' ... see https://tailwindcss.com/docs/border-color
-  , _borderColor_b :: WhenTW Color
-  -- ^ border-b-'Color' ... see https://tailwindcss.com/docs/border-color 
+  , _borderColor_b :: WhenTW (WithTransition Color)
+  -- ^ border-b-'Color' ... see https://tailwindcss.com/docs/border-color
   } deriving Show
 
 instance Default BorderColorSides where
@@ -33,16 +39,17 @@ instance Default BorderColorSides where
 
 instance ShowTW BorderColorSides where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_borderColor_l cfg) ((<>) "border-l-" . showTW)
-    , renderWhenTW (_borderColor_r cfg) ((<>) "border-r-" . showTW)
-    , renderWhenTW (_borderColor_t cfg) ((<>) "border-t-" . showTW)
-    , renderWhenTW (_borderColor_b cfg) ((<>) "border-b-" . showTW)
+    [ renderWithTransitionTW (_borderColor_l cfg) ((<>) "border-l-" . showTW) Transition_Colors
+    , renderWithTransitionTW (_borderColor_r cfg) ((<>) "border-r-" . showTW) Transition_Colors
+    , renderWithTransitionTW (_borderColor_t cfg) ((<>) "border-t-" . showTW) Transition_Colors
+    , renderWithTransitionTW (_borderColor_b cfg) ((<>) "border-b-" . showTW) Transition_Colors
     ]
 
 makeLenses ''BorderColorSides
 
 -- | Like border-'Color', eg border-white
-instance SetSides BorderColorSides Color where
+-- Now uses WithTransition Color so .~~ will auto-wrap, and .~^ allows transitions
+instance SetSides BorderColorSides (WithTransition Color) where
   l = borderColor_l
   r = borderColor_r
   t = borderColor_t
diff --git a/src/Classh/Box/Border/Radius.hs b/src/Classh/Box/Border/Radius.hs
index 9e3518a..d0adb7b 100644
--- a/src/Classh/Box/Border/Radius.hs
+++ b/src/Classh/Box/Border/Radius.hs
@@ -1,3 +1,5 @@
+{-# LANGUAGE FlexibleInstances #-}
+
 module Classh.Box.Border.Radius where
 
 import Classh.Class.ShowTW
@@ -7,23 +9,27 @@ import Classh.Responsive.WhenTW
 import Classh.Internal.Chain
 import Classh.Internal.CSSSize
 import Classh.Internal.TShow
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 import Data.Default
 import Control.Lens (Lens', lens, makeLenses)
 import qualified Data.Text as T
 
--- |Holds 'BorderRadius' by corner
+-- |Holds 'BorderRadius' by corner (transitionable)
 -- see https://tailwindcss.com/docs/border-radius
--- 
+--
 --  For example:
--- 
+--
 -- > elClass "div" $(classh' [ border . radius . borderRadius_tr .~~ R_3Xl, border . radius . borderRadius_tl .~~ R_3Xl ])
 -- > -- Or with shorthand
 -- > elClass "div" $(classh' [ br_t .~~ R_3Xl ])
+-- > -- With transitions:
+-- > elClass "div" $(classh' [ br_t .~^ [("def", R_None), ("hover", R_3Xl `withTransition` Duration_300)] ])
 data BorderRadiusCorners = BorderRadiusCorners
-  { _borderRadius_tr :: WhenTW BorderRadius'
-  , _borderRadius_tl :: WhenTW BorderRadius'
-  , _borderRadius_br :: WhenTW BorderRadius'
-  , _borderRadius_bl :: WhenTW BorderRadius'
+  { _borderRadius_tr :: WhenTW (WithTransition BorderRadius')
+  , _borderRadius_tl :: WhenTW (WithTransition BorderRadius')
+  , _borderRadius_br :: WhenTW (WithTransition BorderRadius')
+  , _borderRadius_bl :: WhenTW (WithTransition BorderRadius')
   } deriving Show
 
 -- | Border radius options, eg R_3Xl ==> "rounded-3xl"
@@ -60,14 +66,14 @@ instance Default BorderRadiusCorners where
 -- TODO: stop overlaps through conditionals
 instance ShowTW BorderRadiusCorners where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_borderRadius_tr cfg) ((<>) "rounded-tr" . showTW)
-    , renderWhenTW (_borderRadius_tl cfg) ((<>) "rounded-tl" . showTW)
-    , renderWhenTW (_borderRadius_br cfg) ((<>) "rounded-br" . showTW)
-    , renderWhenTW (_borderRadius_bl cfg) ((<>) "rounded-bl" . showTW)
+    [ renderWithTransitionTW (_borderRadius_tr cfg) ((<>) "rounded-tr" . showTW) Transition_All
+    , renderWithTransitionTW (_borderRadius_tl cfg) ((<>) "rounded-tl" . showTW) Transition_All
+    , renderWithTransitionTW (_borderRadius_br cfg) ((<>) "rounded-br" . showTW) Transition_All
+    , renderWithTransitionTW (_borderRadius_bl cfg) ((<>) "rounded-bl" . showTW) Transition_All
     ]
 
 -- | Like rounded-(t|r|b|l|tl|...)-'BorderRadius'', eg rounded-tl-xl
-instance SetSides BorderRadiusCorners BorderRadius' where
+instance SetSides BorderRadiusCorners (WithTransition BorderRadius') where
   l = borderRadius_l
   r = borderRadius_r
   b = borderRadius_b
@@ -84,7 +90,7 @@ instance SetSides BorderRadiusCorners BorderRadius' where
 
 
 
-borderRadius_l, borderRadius_r, borderRadius_t, borderRadius_b :: Lens' BorderRadiusCorners (WhenTW BorderRadius')
+borderRadius_l, borderRadius_r, borderRadius_t, borderRadius_b :: Lens' BorderRadiusCorners (WhenTW (WithTransition BorderRadius'))
 borderRadius_l = lens undefined $ \tw new -> tw { _borderRadius_tl = new, _borderRadius_bl = new }
 borderRadius_r = lens undefined $ \tw new -> tw { _borderRadius_tr = new, _borderRadius_br = new }
 borderRadius_t = lens undefined $ \tw new -> tw { _borderRadius_tl = new, _borderRadius_tr = new }
diff --git a/src/Classh/Box/Border/Width.hs b/src/Classh/Box/Border/Width.hs
index 9070522..92596b0 100644
--- a/src/Classh/Box/Border/Width.hs
+++ b/src/Classh/Box/Border/Width.hs
@@ -1,3 +1,5 @@
+{-# LANGUAGE FlexibleInstances #-}
+
 module Classh.Box.Border.Width where
 
 import Classh.Class.ShowTW
@@ -7,23 +9,27 @@ import Classh.Responsive.WhenTW
 import Classh.Internal.Chain
 import Classh.Internal.CSSSize
 import Classh.Internal.TShow
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 import Data.Default
 import Control.Lens (lens, makeLenses)
 import qualified Data.Text as T
 
--- |Holds 'BorderWidth' by side. 
+-- |Holds 'BorderWidth' by side (transitionable).
 --  see https://tailwindcss.com/docs/border-width
--- 
+--
 --  For example:
 --
 --  > elClass "div" $(classh' [ border . bWidth . borderWidth_t .~~ B2 ])
 --  > -- Or with shorthand
 --  > elClass "div" $(classh' [ bw_t .~~ B2 ])
+--  > -- With transitions:
+--  > elClass "div" $(classh' [ bw_t .~^ [("def", B2), ("hover", B4 `withTransition` Duration_300)] ])
 data BorderWidthSides = BorderWidthSides
-  { _borderWidth_l :: WhenTW BorderWidth
-  , _borderWidth_r :: WhenTW BorderWidth
-  , _borderWidth_t :: WhenTW BorderWidth
-  , _borderWidth_b :: WhenTW BorderWidth
+  { _borderWidth_l :: WhenTW (WithTransition BorderWidth)
+  , _borderWidth_r :: WhenTW (WithTransition BorderWidth)
+  , _borderWidth_t :: WhenTW (WithTransition BorderWidth)
+  , _borderWidth_b :: WhenTW (WithTransition BorderWidth)
   } deriving Show
 
 -- | Border Width options, eg. B0 ==> "border-0"
@@ -53,17 +59,17 @@ instance Default BorderWidthSides where
 
 instance ShowTW BorderWidthSides where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_borderWidth_l cfg) ((<>) "border-l" . showTW)
-    , renderWhenTW (_borderWidth_r cfg) ((<>) "border-r" . showTW)
-    , renderWhenTW (_borderWidth_t cfg) ((<>) "border-t" . showTW)
-    , renderWhenTW (_borderWidth_b cfg) ((<>) "border-b" . showTW)
+    [ renderWithTransitionTW (_borderWidth_l cfg) ((<>) "border-l" . showTW) Transition_All
+    , renderWithTransitionTW (_borderWidth_r cfg) ((<>) "border-r" . showTW) Transition_All
+    , renderWithTransitionTW (_borderWidth_t cfg) ((<>) "border-t" . showTW) Transition_All
+    , renderWithTransitionTW (_borderWidth_b cfg) ((<>) "border-b" . showTW) Transition_All
     ]
-    
+
 makeLenses ''BorderWidthSides
 
 
 -- | Like border-l-'BorderWidth', eg border-l-8
-instance SetSides BorderWidthSides BorderWidth where
+instance SetSides BorderWidthSides (WithTransition BorderWidth) where
   l = borderWidth_l
   r = borderWidth_r
   t = borderWidth_t

From f76e8a0cfa8106abeaba4f0751adeb2b2173fd34 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:43:07 -0500
Subject: [PATCH 04/29] feat: update spacing properties to use WithTransition

Update padding and margin properties to support per-value transitions:

BoxPadding:
- All fields: WhenTW TWSize -> WhenTW (WithTransition TWSize)
- Add FlexibleInstances pragma for SetSides instance
- Remove local renderWithTransitionTW/compileWithTransitionTW

BoxMargin:
- All fields: WhenTW TWSize -> WhenTW (WithTransition TWSize)
- Add FlexibleInstances pragma for SetSides instance
- Remove local renderWithTransitionTW definition

Both modules now use centralized rendering helpers from
Classh.WithTransition module.
---
 src/Classh/Box/Margin.hs  | 27 +++++++++++++++------------
 src/Classh/Box/Padding.hs | 33 ++++++++++++++++++---------------
 2 files changed, 33 insertions(+), 27 deletions(-)

diff --git a/src/Classh/Box/Margin.hs b/src/Classh/Box/Margin.hs
index 42f20f0..8acf8cd 100644
--- a/src/Classh/Box/Margin.hs
+++ b/src/Classh/Box/Margin.hs
@@ -1,5 +1,6 @@
 {-# LANGUAGE MultiParamTypeClasses #-}
 {-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE FlexibleInstances #-}
 
 --------------------------------------------------------------------------------
 -- |
@@ -45,8 +46,10 @@ import Classh.Internal.Chain
 import Classh.Class.ShowTW
 import Classh.Class.SetSides
 import Classh.Responsive.WhenTW
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 
-import Classh.Box.TWSize as X 
+import Classh.Box.TWSize as X
 
 import Control.Lens hiding ((<&>))
 import Data.Default
@@ -57,22 +60,22 @@ instance Default BoxMargin where
 
 instance ShowTW BoxMargin where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_marginL cfg) ((<>) "ml-" . showTW)
-    , renderWhenTW (_marginR cfg) ((<>) "mr-" . showTW)
-    , renderWhenTW (_marginT cfg) ((<>) "mt-" . showTW)
-    , renderWhenTW (_marginB cfg) ((<>) "mb-" . showTW)
+    [ renderWithTransitionTW (_marginL cfg) ((<>) "ml-" . showTW) Transition_All
+    , renderWithTransitionTW (_marginR cfg) ((<>) "mr-" . showTW) Transition_All
+    , renderWithTransitionTW (_marginT cfg) ((<>) "mt-" . showTW) Transition_All
+    , renderWithTransitionTW (_marginB cfg) ((<>) "mb-" . showTW) Transition_All
     ]
 
--- | Type representing '_margin' field of 'BoxConfig'.
+-- | Type representing '_margin' field of 'BoxConfig' (transitionable).
 -- | based on https://tailwindcss.com/docs/margin
 data BoxMargin = BoxMargin
-  { _marginL :: WhenTW TWSize
-  -- ^ see shorthand: @ml@ 
-  , _marginR :: WhenTW TWSize
+  { _marginL :: WhenTW (WithTransition TWSize)
+  -- ^ see shorthand: @ml@
+  , _marginR :: WhenTW (WithTransition TWSize)
   -- ^ see shorthand: 'mr'
-  , _marginT :: WhenTW TWSize
+  , _marginT :: WhenTW (WithTransition TWSize)
   -- ^ see shorthand: 'mt'
-  , _marginB :: WhenTW TWSize
+  , _marginB :: WhenTW (WithTransition TWSize)
   -- ^ see shorthand: 'mb'
   } deriving Show
 
@@ -89,7 +92,7 @@ instance Semigroup BoxMargin where
 -- | This is technically an illegal lens however if you ran 2 setters which overlap so that a /= b
 -- | where a and b are the fields associated with respective separate fields, then classh' will
 -- | most likely catch the error. Additionally, there is a lens way to access any field anyways
-instance SetSides BoxMargin TWSize where
+instance SetSides BoxMargin (WithTransition TWSize) where
   l = marginL
   r = marginR
   b = marginB
diff --git a/src/Classh/Box/Padding.hs b/src/Classh/Box/Padding.hs
index dc3d62f..c253e82 100644
--- a/src/Classh/Box/Padding.hs
+++ b/src/Classh/Box/Padding.hs
@@ -1,5 +1,6 @@
 {-# LANGUAGE MultiParamTypeClasses #-}
 {-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE FlexibleInstances #-}
 
 --------------------------------------------------------------------------------
 -- |
@@ -47,8 +48,10 @@ import Classh.Class.ShowTW
 import Classh.Class.SetSides
 import Classh.Class.CompileStyle
 import Classh.Responsive.WhenTW
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 
-import Classh.Box.TWSize as X 
+import Classh.Box.TWSize as X
 
 import Control.Lens hiding ((<&>))
 import Data.Default
@@ -63,10 +66,10 @@ instance Default BoxPadding where
 
 instance ShowTW BoxPadding where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_paddingL cfg) ((<>) "pl-" . showTW)
-    , renderWhenTW (_paddingR cfg) ((<>) "pr-" . showTW)
-    , renderWhenTW (_paddingT cfg) ((<>) "pt-" . showTW)
-    , renderWhenTW (_paddingB cfg) ((<>) "pb-" . showTW)
+    [ renderWithTransitionTW (_paddingL cfg) ((<>) "pl-" . showTW) Transition_All
+    , renderWithTransitionTW (_paddingR cfg) ((<>) "pr-" . showTW) Transition_All
+    , renderWithTransitionTW (_paddingT cfg) ((<>) "pt-" . showTW) Transition_All
+    , renderWithTransitionTW (_paddingB cfg) ((<>) "pb-" . showTW) Transition_All
     ]
 
 -- | For row func
@@ -75,22 +78,22 @@ instance CompileStyle BoxPadding where
 
 compilePadding :: BoxPadding -> Either T.Text T.Text
 compilePadding cfg = pure . foldr (<&>) mempty =<< sequenceA
-  [ compileWhenTW (_paddingL cfg) ((<>) "pl-" . showTW)
-  , compileWhenTW (_paddingR cfg) ((<>) "pr-" . showTW)
-  , compileWhenTW (_paddingT cfg) ((<>) "pt-" . showTW)
-  , compileWhenTW (_paddingB cfg) ((<>) "pb-" . showTW)
+  [ compileWithTransitionTW (_paddingL cfg) ((<>) "pl-" . showTW) Transition_All
+  , compileWithTransitionTW (_paddingR cfg) ((<>) "pr-" . showTW) Transition_All
+  , compileWithTransitionTW (_paddingT cfg) ((<>) "pt-" . showTW) Transition_All
+  , compileWithTransitionTW (_paddingB cfg) ((<>) "pb-" . showTW) Transition_All
   ]
 
--- | Type representing '_padding' field of 'BoxConfig'.
+-- | Type representing '_padding' field of 'BoxConfig' (transitionable).
 -- | based on https://tailwindcss.com/docs/padding
 data BoxPadding = BoxPadding
-  { _paddingL :: WhenTW TWSize
+  { _paddingL :: WhenTW (WithTransition TWSize)
   -- ^ see shorthand: pl
-  , _paddingR :: WhenTW TWSize
+  , _paddingR :: WhenTW (WithTransition TWSize)
   -- ^ see shorthand: pr
-  , _paddingT :: WhenTW TWSize
+  , _paddingT :: WhenTW (WithTransition TWSize)
   -- ^ see shorthand: pt
-  , _paddingB :: WhenTW TWSize
+  , _paddingB :: WhenTW (WithTransition TWSize)
   -- ^ see shorthand: pb
   } deriving Show
 
@@ -107,7 +110,7 @@ instance Semigroup BoxPadding where
 -- | This is technically an illegal lens however if you ran 2 setters which overlap so that a /= b
 -- | where a and b are the fields associated with respective separate fields, then classh' will
 -- | most likely catch the error. Additionally, there is a lens way to access any field anyways
-instance SetSides BoxPadding TWSize where
+instance SetSides BoxPadding (WithTransition TWSize) where
   l = paddingL
   r = paddingR
   b = paddingB

From bcbc21bcfb864710c0c61653fbd4c00a352d42b8 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:43:33 -0500
Subject: [PATCH 05/29] feat: update sizing properties to use WithTransition

Update all sizing-related properties to support per-value transitions:

BoxSizing:
- _width: WhenTW TWSizeOrFraction -> WhenTW (WithTransition TWSizeOrFraction)
- _height: WhenTW TWSizeOrFraction -> WhenTW (WithTransition TWSizeOrFraction)

BoxSizingConstraint:
- _widthC: WhenTW DimensionConstraint -> WhenTW (WithTransition DimensionConstraint)
- _heightC: WhenTW DimensionConstraint -> WhenTW (WithTransition DimensionConstraint)

SizingBand:
- Remove local renderWithTransitionTW definition
- Use centralized version from Classh.WithTransition

This enables smooth transitions for width, height, min/max constraints
across responsive breakpoints and pseudo-classes.
---
 src/Classh/Box/Sizing/BoxSizing.hs           | 12 +++++++-----
 src/Classh/Box/Sizing/BoxSizingConstraint.hs |  5 +++--
 src/Classh/Box/SizingBand.hs                 | 14 ++++++++------
 3 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/src/Classh/Box/Sizing/BoxSizing.hs b/src/Classh/Box/Sizing/BoxSizing.hs
index 60c2a6a..4101ae4 100644
--- a/src/Classh/Box/Sizing/BoxSizing.hs
+++ b/src/Classh/Box/Sizing/BoxSizing.hs
@@ -38,13 +38,15 @@ import Classh.Internal.Chain
 import Classh.Class.ShowTW
 import Classh.Responsive.WhenTW
 import Classh.Box.TWSize
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 import Data.Default
 import Control.Lens (makeLenses)
 
--- | Holds information on target sizing, which will be overrided by constraints
+-- | Holds information on target sizing (transitionable), which will be overrided by constraints
 data BoxSizing = BoxSizing
-  { _width :: WhenTW TWSizeOrFraction
-  , _height :: WhenTW TWSizeOrFraction
+  { _width :: WhenTW (WithTransition TWSizeOrFraction)
+  , _height :: WhenTW (WithTransition TWSizeOrFraction)
   }
   deriving Show
 
@@ -54,8 +56,8 @@ instance Default BoxSizing where
 
 instance ShowTW BoxSizing where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_width cfg) ((<>) "w-" . showTW)
-    , renderWhenTW (_height cfg) ((<>) "h-" . showTW)
+    [ renderWithTransitionTW (_width cfg) ((<>) "w-" . showTW) Transition_All
+    , renderWithTransitionTW (_height cfg) ((<>) "h-" . showTW) Transition_All
     ]
 
 makeLenses ''BoxSizing
diff --git a/src/Classh/Box/Sizing/BoxSizingConstraint.hs b/src/Classh/Box/Sizing/BoxSizingConstraint.hs
index c343fc4..48177ac 100644
--- a/src/Classh/Box/Sizing/BoxSizingConstraint.hs
+++ b/src/Classh/Box/Sizing/BoxSizingConstraint.hs
@@ -34,6 +34,7 @@ module Classh.Box.Sizing.BoxSizingConstraint
 
 import Classh.Box.Sizing.DimensionConstraint as X
 import Classh.Responsive.WhenTW
+import Classh.WithTransition
 import Control.Lens (makeLenses)
 import Data.Default
 
@@ -42,8 +43,8 @@ instance Default BoxSizingConstraint where
   def = BoxSizingConstraint def def
 
 data BoxSizingConstraint = BoxSizingConstraint
-  { _widthC :: WhenTW DimensionConstraint
-  , _heightC :: WhenTW DimensionConstraint
+  { _widthC :: WhenTW (WithTransition DimensionConstraint)
+  , _heightC :: WhenTW (WithTransition DimensionConstraint)
   }
   deriving Show
 
diff --git a/src/Classh/Box/SizingBand.hs b/src/Classh/Box/SizingBand.hs
index bdfc213..f808e13 100644
--- a/src/Classh/Box/SizingBand.hs
+++ b/src/Classh/Box/SizingBand.hs
@@ -49,6 +49,8 @@ import Classh.Class.ShowTW
 import Classh.Responsive.WhenTW
 import Classh.Internal.Chain
 import Classh.Responsive.ZipScreens
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 
 import Classh.Box.TWSize as X
 
@@ -56,15 +58,15 @@ import Control.Lens (makeLenses)
 import Data.Default
 
 -- move to shorthand?
-fitToContents :: (WhenTW TWSizeOrFraction, WhenTW TWSizeOrFraction)
-fitToContents = (only TWSize_Fit, only TWSize_Fit)
+fitToContents :: (WhenTW (WithTransition TWSizeOrFraction), WhenTW (WithTransition TWSizeOrFraction))
+fitToContents = (only (WithTransition TWSize_Fit Nothing), only (WithTransition TWSize_Fit Nothing))
 
 instance ShowTW BoxSizingBand where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_widthC . _maxSize $ cfg) ((<>) "max-w-" . showTW)
-    , renderWhenTW (_heightC . _maxSize $ cfg) ((<>) "max-h-" . showTW)
-    , renderWhenTW (_widthC . _minSize $ cfg) ((<>) "min-w-" . showTW)
-    , renderWhenTW (_heightC . _minSize $ cfg) ((<>) "min-h-" . showTW)
+    [ renderWithTransitionTW (_widthC . _maxSize $ cfg) ((<>) "max-w-" . showTW) Transition_All
+    , renderWithTransitionTW (_heightC . _maxSize $ cfg) ((<>) "max-h-" . showTW) Transition_All
+    , renderWithTransitionTW (_widthC . _minSize $ cfg) ((<>) "min-w-" . showTW) Transition_All
+    , renderWithTransitionTW (_heightC . _minSize $ cfg) ((<>) "min-h-" . showTW) Transition_All
     , showTW $ _size cfg
     ]
 

From 8afdabbf77bf393068378723bd0a16597c2b3517 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:44:06 -0500
Subject: [PATCH 06/29] feat: update ring properties to use WithTransition

Update RingConfig to support per-value transitions:

- _ringWidth: WhenTW RingWidth -> WhenTW (WithTransition RingWidth)
- _ringColor: WhenTW Color -> WhenTW (WithTransition Color)
- _ringOpacity: WhenTW Int -> WhenTW (WithTransition Int)

Remove local renderWithTransitionTW definition, use centralized version
from Classh.WithTransition module.

Enables smooth transitions for focus rings with proper transition property
inference (Transition_All for width, Transition_Colors for color,
Transition_Opacity for opacity).
---
 src/Classh/Box/Ring.hs | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/Classh/Box/Ring.hs b/src/Classh/Box/Ring.hs
index 427a5b4..188edec 100644
--- a/src/Classh/Box/Ring.hs
+++ b/src/Classh/Box/Ring.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE FlexibleInstances #-}
 
 --------------------------------------------------------------------------------
 -- |
@@ -32,6 +33,8 @@ import Classh.Internal.TShow
 import Classh.Internal.Chain
 import Classh.Responsive.WhenTW
 import Classh.Color
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
 import Control.Lens (makeLenses)
 import Data.Default
 import qualified Data.Text as T
@@ -48,11 +51,11 @@ data RingWidth
   | Ring_Inset
   deriving Show
 
--- | Ring configuration
+-- | Ring configuration (transitionable)
 data RingConfig = RingConfig
-  { _ringWidth :: WhenTW RingWidth
-  , _ringColor :: WhenTW Color
-  , _ringOpacity :: WhenTW Int  -- 0-100
+  { _ringWidth :: WhenTW (WithTransition RingWidth)
+  , _ringColor :: WhenTW (WithTransition Color)
+  , _ringOpacity :: WhenTW (WithTransition Int)  -- 0-100
   } deriving Show
 
 makeLenses ''RingConfig
@@ -72,9 +75,9 @@ instance Default RingConfig where
 
 instance ShowTW RingConfig where
   showTW cfg = foldr (<&>) mempty
-    [ renderWhenTW (_ringWidth cfg) showTW
-    , renderWhenTW (_ringColor cfg) ((<>) "ring-" . showTW)
-    , renderWhenTW (_ringOpacity cfg) ((<>) "ring-opacity-" . tshow)
+    [ renderWithTransitionTW (_ringWidth cfg) showTW Transition_All
+    , renderWithTransitionTW (_ringColor cfg) ((<>) "ring-" . showTW) Transition_Colors
+    , renderWithTransitionTW (_ringOpacity cfg) ((<>) "ring-opacity-" . tshow) Transition_Opacity
     ]
 
 instance Semigroup RingConfig where

From 91a388bfea0391311962423b4dc076b84e84809b Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:45:01 -0500
Subject: [PATCH 07/29] feat: add AutoWrap support to setter operators for
 backwards compatibility

Update all setter operators to use AutoWrap typeclass:

- (.~~): Single value setter now auto-wraps plain values in WithTransition
- (.|~): List-based setter now auto-wraps plain values in WithTransition
- (.~+): Append setter now auto-wraps plain values in WithTransition
- (.~^): New explicit transition setter for [(TWCondition, WithTransition a)]

This enables backwards compatibility, allowing existing code like:
  bgColor .~~ purple
to work seamlessly with new WithTransition types, while also supporting:
  bgColor .~~ (purple `withTransition` Duration_300)

The AutoWrap typeclass automatically wraps bare values when needed.
---
 src/Classh/Setters.hs | 48 +++++++++++++++++++++++++++++--------------
 1 file changed, 33 insertions(+), 15 deletions(-)

diff --git a/src/Classh/Setters.hs b/src/Classh/Setters.hs
index 07c24cc..9aea160 100644
--- a/src/Classh/Setters.hs
+++ b/src/Classh/Setters.hs
@@ -31,6 +31,7 @@ module Classh.Setters where
 
 import Classh.Responsive.WhenTW
 import Classh.Responsive.ZipScreens
+import Classh.WithTransition
 import Control.Lens hiding (only)
 
 -- | Append a list to existing WhenTW field of a config
@@ -43,36 +44,53 @@ infixr 4 .+
 (.+) :: ASetter s t [a] [a] -> [a] -> s -> t
 (.+) = (.~+)
 
--- | Extend existing WhenTW field of a config with new value at end of input list 
+-- | Extend existing WhenTW field of a config with new value at end of input list
 infixr 4 .++
-(.++) :: ASetter s t (WhenTW a) (WhenTW a) -> a -> s -> t
-someLens .++ newVals = over someLens (++ (only newVals))
+(.++) :: AutoWrap a b => ASetter s t (WhenTW b) (WhenTW b) -> a -> s -> t
+someLens .++ newVals = over someLens (++ (only $ autoWrap newVals))
 
 -- | Set property to a singular constant value
+-- Uses AutoWrap to automatically wrap values in WithTransition when needed
 infixr 4 .~~
-(.~~) :: ASetter s t b (WhenTW a) -> a -> s -> t
-someLens .~~ newVals = over someLens (const $ only newVals)
+(.~~) :: AutoWrap a b => ASetter s t c (WhenTW b) -> a -> s -> t
+someLens .~~ newVals = over someLens (const $ only $ autoWrap newVals)
 
 -- | Zip input list with screen sizes to create a responsive property and override
+-- Uses AutoWrap to automatically wrap values in WithTransition when needed
 infixr 4 .|~
-(.|~) :: ASetter s t b (WhenTW a) -> [a] -> s -> t
-someLens .|~ newVals = over someLens (const $ zipScreens newVals)
+(.|~) :: AutoWrap a b => ASetter s t c (WhenTW b) -> [a] -> s -> t
+someLens .|~ newVals = over someLens (const $ zipScreens $ fmap autoWrap newVals)
 
 -- | Zip input list with screen sizes to create a responsive property and add to input property
+-- Uses AutoWrap to automatically wrap values in WithTransition when needed
 infixr 4 .|+
-(.|+) :: ASetter s t (WhenTW a) (WhenTW a) -> [a] -> s -> t
-someLens .|+ newVals = over someLens (++ (zipScreens newVals))
+(.|+) :: AutoWrap a b => ASetter s t (WhenTW b) (WhenTW b) -> [a] -> s -> t
+someLens .|+ newVals = over someLens (++ (zipScreens $ fmap autoWrap newVals))
 
 
 
--- | Both are functions from Classh with changed infix precedence to work with <> 
-infixr 7 .- 
-(.-) :: ASetter s t b (WhenTW a) -> a -> s -> t
-someLens .- newVals = over someLens (const $ only newVals)
+-- | Both are functions from Classh with changed infix precedence to work with <>
+-- Uses AutoWrap to automatically wrap values in WithTransition when needed
+infixr 7 .-
+(.-) :: AutoWrap a b => ASetter s t c (WhenTW b) -> a -> s -> t
+someLens .- newVals = over someLens (const $ only $ autoWrap newVals)
 
 infixr 7 .|<~
-(.|<~) :: ASetter s t b (WhenTW a) -> [a] -> s -> t
-someLens .|<~ newVals = over someLens (const $ zipScreens newVals)
+(.|<~) :: AutoWrap a b => ASetter s t c (WhenTW b) -> [a] -> s -> t
+someLens .|<~ newVals = over someLens (const $ zipScreens $ fmap autoWrap newVals)
+
+-- | Set property with explicit transition support
+-- This operator allows you to specify transitions per-condition
+--
+-- Example:
+-- @
+--   bgColor .~^ [ ("def", purple)
+--               , ("hover", lavender `withTransition` Duration_300)
+--               ]
+-- @
+infixr 4 .~^
+(.~^) :: ASetter s t c (WhenTW (WithTransition a)) -> [(TWCondition, WithTransition a)] -> s -> t
+someLens .~^ newVals = over someLens (const newVals)
 
 
 -- .:|

From a48193cf42985284ad554ab934e570f81da3c7b9 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:45:42 -0500
Subject: [PATCH 08/29] feat: update shorthand type signatures for
 WithTransition

Update all shorthand setter type signatures to match new WithTransition
types:

Border shortcuts:
- br_*, bw_*, bc_*: Now use WhenTW (WithTransition X)

Sizing shortcuts:
- w, h, width', height': WhenTW (WithTransition TWSizeOrFraction)
- maxW, minW, maxH, minH: WhenTW (WithTransition DimensionConstraint)

Spacing shortcuts:
- mt, mb, ml, mr, mx, my, m: WhenTW (WithTransition TWSize)
- pt, pb, pl, pr, px, py, p: WhenTW (WithTransition TWSize)

All shortcuts now support both plain values (auto-wrapped) and explicit
transitions via the AutoWrap typeclass.
---
 src/Classh/Shorthand.hs | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/src/Classh/Shorthand.hs b/src/Classh/Shorthand.hs
index 5288663..6aba3c1 100644
--- a/src/Classh/Shorthand.hs
+++ b/src/Classh/Shorthand.hs
@@ -40,27 +40,27 @@ import Control.Lens (Lens')
 type Setter a b = Lens' a b
 
 -- | Set border radius side(s)
-br_r, br_l, br_t, br_b, br_y, br_x, br :: Setter BoxConfig (WhenTW BorderRadius')
-br_r = border . radius . r 
+br_r, br_l, br_t, br_b, br_y, br_x, br :: Setter BoxConfig (WhenTW (WithTransition BorderRadius'))
+br_r = border . radius . r
 br_l = border . radius . l
 br_t = border . radius . t
 br_b = border . radius . b
 br_y = border . radius . y
 br_x = border . radius . x
-br = border . radius . allS 
+br = border . radius . allS
 
 -- | Set border width side(s)
-bw_r, bw_l, bw_t, bw_b, bw_y, bw_x, bw :: Setter BoxConfig (WhenTW BorderWidth)
-bw_r = border . bWidth . r 
+bw_r, bw_l, bw_t, bw_b, bw_y, bw_x, bw :: Setter BoxConfig (WhenTW (WithTransition BorderWidth))
+bw_r = border . bWidth . r
 bw_l = border . bWidth . l
 bw_t = border . bWidth . t
 bw_b = border . bWidth . b
 bw_y = border . bWidth . y
 bw_x = border . bWidth . x
-bw = border . bWidth . allS 
+bw = border . bWidth . allS
 
 -- | Set border color side(s)
-bc_r, bc_l, bc_t, bc_b, bc_y, bc_x, bc :: Setter BoxConfig (WhenTW Color)
+bc_r, bc_l, bc_t, bc_b, bc_y, bc_x, bc :: Setter BoxConfig (WhenTW (WithTransition Color))
 bc_r = border . bColor . r 
 bc_l = border . bColor . l
 bc_t = border . bColor . t
@@ -74,33 +74,33 @@ pos :: Setter BoxConfig (WhenTW (Justify, Align))
 pos = position
 
 -- | Set width
-width' :: Setter BoxConfig (WhenTW TWSizeOrFraction)
+width' :: Setter BoxConfig (WhenTW (WithTransition TWSizeOrFraction))
 width' = sizingBand . size . width
 -- | Set width
-w :: Setter BoxConfig (WhenTW TWSizeOrFraction)
+w :: Setter BoxConfig (WhenTW (WithTransition TWSizeOrFraction))
 w = width'
 -- | Set height
-height' :: Setter BoxConfig (WhenTW TWSizeOrFraction)
+height' :: Setter BoxConfig (WhenTW (WithTransition TWSizeOrFraction))
 height' = sizingBand . size . height
 -- | Set height
-h :: Setter BoxConfig (WhenTW TWSizeOrFraction)
+h :: Setter BoxConfig (WhenTW (WithTransition TWSizeOrFraction))
 h = height'
 
--- | Set BoxConfig max width 
-maxW :: Setter BoxConfig (WhenTW DimensionConstraint)
+-- | Set BoxConfig max width
+maxW :: Setter BoxConfig (WhenTW (WithTransition DimensionConstraint))
 maxW = sizingBand . maxSize . widthC
 -- | Set BoxConfig min width
-minW :: Setter BoxConfig (WhenTW DimensionConstraint)
+minW :: Setter BoxConfig (WhenTW (WithTransition DimensionConstraint))
 minW = sizingBand . minSize . widthC
 -- | Set BoxConfig max height
-maxH :: Setter BoxConfig (WhenTW DimensionConstraint)
+maxH :: Setter BoxConfig (WhenTW (WithTransition DimensionConstraint))
 maxH = sizingBand . maxSize . heightC
 -- | Set BoxConfig min height
-minH :: Setter BoxConfig (WhenTW DimensionConstraint)
-minH = sizingBand . minSize . heightC 
+minH :: Setter BoxConfig (WhenTW (WithTransition DimensionConstraint))
+minH = sizingBand . minSize . heightC
 
 -- | Set margin on a given side(s)
-mt, ml, mr, mb, mx, my, m :: Setter BoxConfig (WhenTW TWSize)
+mt, ml, mr, mb, mx, my, m :: Setter BoxConfig (WhenTW (WithTransition TWSize))
 mt = margin . t
 mb = margin . b
 ml = margin . l
@@ -110,7 +110,7 @@ my = margin . y
 m = margin . allS
 
 -- | Set padding on a given side(s)
-pt, pl, pr, pb, px, py, p :: Setter BoxConfig (WhenTW TWSize)
+pt, pl, pr, pb, px, py, p :: Setter BoxConfig (WhenTW (WithTransition TWSize))
 pt = padding . t
 pb = padding . b
 pl = padding . l

From 2c92accb41d65754c5142ee8ab96db347a884737 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:46:06 -0500
Subject: [PATCH 09/29] chore: expose WithTransition module in cabal file

Add Classh.WithTransition to exposed-modules in ClasshSS.cabal.

Also add documentation comment to WhenTW module explaining that
WithTransition rendering helpers are defined in a separate module
to avoid circular dependencies.
---
 ClasshSS.cabal                  | 3 ++-
 src/Classh/Responsive/WhenTW.hs | 6 ++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/ClasshSS.cabal b/ClasshSS.cabal
index a61edab..7ba1d4a 100644
--- a/ClasshSS.cabal
+++ b/ClasshSS.cabal
@@ -93,7 +93,8 @@ library
                      Classh.TextPosition.WhiteSpace
                      Classh.TextPosition.WordBreak
                      Classh.TextPosition.Wrap
-                     
+                     Classh.WithTransition
+
 
     default-extensions:
         OverloadedStrings
diff --git a/src/Classh/Responsive/WhenTW.hs b/src/Classh/Responsive/WhenTW.hs
index 3e83473..98491d7 100644
--- a/src/Classh/Responsive/WhenTW.hs
+++ b/src/Classh/Responsive/WhenTW.hs
@@ -67,3 +67,9 @@ mkConditionPrefix c = if c == "def" then "" else (c <> ":")
 -- eg. width2 = width1 + 1px
 instance Functor WhenTW' where
   fmap f whenTW = WhenTW' $ fmap (\(c,a) -> (c, f a)) $ unWhenTW whenTW
+
+-- | Render WhenTW values that are wrapped in WithTransition
+-- This extracts the value, renders it, and adds transition classes if present
+-- Note: This requires importing Classh.WithTransition and Classh.Box.Transition
+-- but we can't do that here to avoid circular dependencies
+-- So we'll define this in a separate module or inline where needed

From 67f3410b5c92758fcaa7fd2330094b29db206a04 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 14:47:16 -0500
Subject: [PATCH 10/29] test: add WithTransition functionality tests

Add TransitionTest.hs demonstrating various transition usage patterns:

- Test 1: Backwards compatibility with plain values (no transitions)
- Test 2: Using (.~^) operator with noTransition and withTransition
- Test 3: Builder pattern with chaining (withTransition, withTiming, withDelay)
- Test 4: All-at-once style with withTransitionAll

Tests cover responsive breakpoints (sm), pseudo-classes (hover, focus),
and various transition configurations (duration, timing, delay).
---
 test/TransitionTest.hs | 63 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 test/TransitionTest.hs

diff --git a/test/TransitionTest.hs b/test/TransitionTest.hs
new file mode 100644
index 0000000..6f5e169
--- /dev/null
+++ b/test/TransitionTest.hs
@@ -0,0 +1,63 @@
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module Main where
+
+import Classh
+import Classh.Box
+import Classh.Color
+import Classh.Box.Transition
+import Classh.WithTransition
+import Classh.Setters
+import Classh.Class.CompileStyle
+
+-- Test 1: Backwards compatible - no transitions
+test1 :: BoxConfig
+test1 = def
+  & bgColor .~~ (Gray C500)
+  & colSpan .~~ 2
+
+-- Test 2: Using new (.~^) operator with builder pattern
+test2 :: BoxConfig
+test2 = def
+  & bgColor .~^ [ ("def", noTransition (Gray C500))
+                , ("hover", (Gray C300) `withTransition` Duration_300)
+                ]
+
+-- Test 3: Builder pattern with chaining
+test3 :: BoxConfig
+test3 = def
+  & bgColor .~^ [ ("def", noTransition Purple)
+                , ("hover", Lavender `withTransition` Duration_300 `withTiming` Ease_InOut)
+                , ("focus", Indigo `withTransition` Duration_500 `withTiming` Ease_Out `withDelay` Delay_100)
+                ]
+
+-- Test 4: All-at-once style
+test4 :: BoxConfig
+test4 = def
+  & bgColor .~^ [ ("def", noTransition Purple)
+                , ("sm", Indigo `withTransitionAll` Duration_300 Ease_InOut Delay_0)
+                , ("hover", Lavender `withTransition` Duration_500)
+                ]
+
+main :: IO ()
+main = do
+  putStrLn "Test 1 (backwards compatible):"
+  case compileS test1 of
+    Left err -> putStrLn $ "Error: " ++ show err
+    Right result -> putStrLn $ "  " ++ show result
+
+  putStrLn "\nTest 2 (hover with transition):"
+  case compileS test2 of
+    Left err -> putStrLn $ "Error: " ++ show err
+    Right result -> putStrLn $ "  " ++ show result
+
+  putStrLn "\nTest 3 (builder pattern with chaining):"
+  case compileS test3 of
+    Left err -> putStrLn $ "Error: " ++ show err
+    Right result -> putStrLn $ "  " ++ show result
+
+  putStrLn "\nTest 4 (all-at-once style):"
+  case compileS test4 of
+    Left err -> putStrLn $ "Error: " ++ show err
+    Right result -> putStrLn $ "  " ++ show result

From 664ae67d940c4470b88e34367dda65754a6dbbdd Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 16:12:23 -0500
Subject: [PATCH 11/29] refactor: remove unused AutoWrap typeclass

The AutoWrap typeclass is no longer needed as we've replaced it with
a more robust approach using SetConstant, SetResponsive, and AddResponsive
typeclasses that properly handle type inference.
---
 src/Classh/WithTransition.hs | 19 -------------------
 1 file changed, 19 deletions(-)

diff --git a/src/Classh/WithTransition.hs b/src/Classh/WithTransition.hs
index 02115e4..0285ba4 100644
--- a/src/Classh/WithTransition.hs
+++ b/src/Classh/WithTransition.hs
@@ -85,25 +85,6 @@ withTransitionFull val cfg = WithTransition val (Just cfg)
 noTransition :: a -> WithTransition a
 noTransition val = WithTransition val Nothing
 
--- | Type class for automatic wrapping in WithTransition
--- This enables backwards compatibility for existing operators
-class AutoWrap a b where
-  autoWrap :: a -> b
-
--- | Wrap plain values in WithTransition with Nothing
--- This makes existing code work: bgColor .~~ purple
-instance AutoWrap a (WithTransition a) where
-  autoWrap a = WithTransition a Nothing
-
--- | Pass through values that don't need wrapping
--- This makes existing code work: colStart .~~ 2
-instance {-# OVERLAPPABLE #-} AutoWrap a a where
-  autoWrap = id
-
--- | Pass through values that are already wrapped
-instance AutoWrap (WithTransition a) (WithTransition a) where
-  autoWrap = id
-
 instance Default a => Default (WithTransition a) where
   def = WithTransition def Nothing
 

From e3d3833e43189ac21b4382a50d576ec82027e0cd Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 16:15:40 -0500
Subject: [PATCH 12/29] feat: use typeclasses for proper type inference in
 setters

Replace AutoWrap with SetConstant, SetResponsive, and AddResponsive
typeclasses that use type families (UnwrapType) to enable proper type
inference from lens types.

This allows expressions like `h .~~ pct 100` to work without type
annotations - the compiler infers that pct should return TWSizeOrFraction
based on the height lens type.

Key changes:
- Add SetConstant typeclass for (.~~) operator
- Add SetResponsive typeclass for (.|~) operator
- Add AddResponsive typeclass for (.|+) operator
- Use UnwrapType family to extract unwrapped types
- For WithTransition fields, automatically wrap values with noTransition
- For plain fields, use values directly
---
 src/Classh/Setters.hs | 77 +++++++++++++++++++++++++++++--------------
 1 file changed, 53 insertions(+), 24 deletions(-)

diff --git a/src/Classh/Setters.hs b/src/Classh/Setters.hs
index 9aea160..5d61484 100644
--- a/src/Classh/Setters.hs
+++ b/src/Classh/Setters.hs
@@ -1,6 +1,12 @@
+{-# LANGUAGE TypeFamilies #-}
+{-# LANGUAGE FlexibleInstances #-}
+{-# LANGUAGE MultiParamTypeClasses #-}
+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE FunctionalDependencies #-}
+
 --------------------------------------------------------------------------------
 -- |
---  Module      :  Classh.Box.Border
+--  Module      :  Classh.Setters
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -8,7 +14,7 @@
 --  Stability   :  provisional
 --  Portability :  portable
 --
---  Types to represent tailwind box's border config of 'BoxConfig'  
+--  Setter operators for ClasshSS configs
 --
 --  Any field named _someField has an associated lens `someField`
 --  see @defaultNameTransform@ from Lens.Family.THCore
@@ -34,50 +40,73 @@ import Classh.Responsive.ZipScreens
 import Classh.WithTransition
 import Control.Lens hiding (only)
 
--- | Append a list to existing WhenTW field of a config
+-- | Append a list to existing WhenTW field of a config (for non-transitionable fields)
 infixr 4 .~+
-(.~+) :: ASetter s t [a] [a] -> [a] -> s -> t
+(.~+) :: ASetter s t (WhenTW a) (WhenTW a) -> WhenTW a -> s -> t
 someLens .~+ newVals = over someLens (++ newVals)
 
--- | Append a list to existing WhenTW field of a config
+-- | Append a list to existing WhenTW field of a config (for non-transitionable fields)
 infixr 4 .+
-(.+) :: ASetter s t [a] [a] -> [a] -> s -> t
+(.+) :: ASetter s t (WhenTW a) (WhenTW a) -> WhenTW a -> s -> t
 (.+) = (.~+)
 
--- | Extend existing WhenTW field of a config with new value at end of input list
+-- | Extend existing WhenTW field with single value (for non-transitionable fields)
 infixr 4 .++
-(.++) :: AutoWrap a b => ASetter s t (WhenTW b) (WhenTW b) -> a -> s -> t
-someLens .++ newVals = over someLens (++ (only $ autoWrap newVals))
+(.++) :: ASetter s t (WhenTW a) (WhenTW a) -> a -> s -> t
+someLens .++ newVals = over someLens (++ (only newVals))
+
+type family UnwrapType a where
+  UnwrapType (WithTransition a) = a
+  UnwrapType a = a
 
 -- | Set property to a singular constant value
--- Uses AutoWrap to automatically wrap values in WithTransition when needed
+-- For WithTransition fields, takes unwrapped value and wraps with noTransition
+-- For plain fields, takes value directly
+-- User always provides unwrapped values to (.~~)
 infixr 4 .~~
-(.~~) :: AutoWrap a b => ASetter s t c (WhenTW b) -> a -> s -> t
-someLens .~~ newVals = over someLens (const $ only $ autoWrap newVals)
+class SetConstant field where
+  (.~~) :: ASetter s t c (WhenTW field) -> UnwrapType field -> s -> t
+
+instance SetConstant (WithTransition a) where
+  someLens .~~ newVals = over someLens (const $ only $ noTransition newVals)
+
+instance {-# OVERLAPPABLE #-} (UnwrapType a ~ a) => SetConstant a where
+  someLens .~~ newVals = over someLens (const $ only newVals)
 
 -- | Zip input list with screen sizes to create a responsive property and override
--- Uses AutoWrap to automatically wrap values in WithTransition when needed
+-- Works for both transitionable and non-transitionable fields
 infixr 4 .|~
-(.|~) :: AutoWrap a b => ASetter s t c (WhenTW b) -> [a] -> s -> t
-someLens .|~ newVals = over someLens (const $ zipScreens $ fmap autoWrap newVals)
+class SetResponsive a where
+  (.|~) :: ASetter s t c (WhenTW a) -> [UnwrapType a] -> s -> t
 
--- | Zip input list with screen sizes to create a responsive property and add to input property
--- Uses AutoWrap to automatically wrap values in WithTransition when needed
+instance SetResponsive (WithTransition a) where
+  someLens .|~ newVals = over someLens (const $ zipScreens $ fmap noTransition newVals)
+
+instance {-# OVERLAPPABLE #-} (UnwrapType a ~ a) => SetResponsive a where
+  someLens .|~ newVals = over someLens (const $ zipScreens newVals)
+
+-- | Zip input list with screen sizes and add to existing property
+-- Works for both transitionable and non-transitionable fields
 infixr 4 .|+
-(.|+) :: AutoWrap a b => ASetter s t (WhenTW b) (WhenTW b) -> [a] -> s -> t
-someLens .|+ newVals = over someLens (++ (zipScreens $ fmap autoWrap newVals))
+class AddResponsive a where
+  (.|+) :: ASetter s t (WhenTW a) (WhenTW a) -> [UnwrapType a] -> s -> t
+
+instance AddResponsive (WithTransition a) where
+  someLens .|+ newVals = over someLens (++ (zipScreens $ fmap noTransition newVals))
+
+instance {-# OVERLAPPABLE #-} (UnwrapType a ~ a) => AddResponsive a where
+  someLens .|+ newVals = over someLens (++ (zipScreens newVals))
 
 
 
 -- | Both are functions from Classh with changed infix precedence to work with <>
--- Uses AutoWrap to automatically wrap values in WithTransition when needed
 infixr 7 .-
-(.-) :: AutoWrap a b => ASetter s t c (WhenTW b) -> a -> s -> t
-someLens .- newVals = over someLens (const $ only $ autoWrap newVals)
+(.-) :: SetConstant a => ASetter s t c (WhenTW a) -> UnwrapType a -> s -> t
+(.-) = (.~~)
 
 infixr 7 .|<~
-(.|<~) :: AutoWrap a b => ASetter s t c (WhenTW b) -> [a] -> s -> t
-someLens .|<~ newVals = over someLens (const $ zipScreens $ fmap autoWrap newVals)
+(.|<~) :: SetResponsive a => ASetter s t c (WhenTW a) -> [UnwrapType a] -> s -> t
+(.|<~) = (.|~)
 
 -- | Set property with explicit transition support
 -- This operator allows you to specify transitions per-condition

From 1d5e406f3c25ea31e808816ca657cc52af3856a5 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 21:36:49 -0500
Subject: [PATCH 13/29] feat: implement per-attribute transitions with
 arbitrary Tailwind syntax

- Remove global _transition field from BoxConfig
- Update transition rendering to use arbitrary value syntax: [transition:property_duration_timing_delay]
- Add transitionPropertyToCSSName and transitionTimingToCSSName helpers
- Fix timing function conversion (in-out vs inout)
- Add functional dependency to SetSides class for better type inference
- Change from INCOHERENT to OVERLAPPING/OVERLAPPABLE pragmas in Setters

All transitions are now per-attribute using the WithTransition wrapper type,
generating Tailwind arbitrary values like:
hover:[transition:background-color,border-color,color,fill,stroke_300ms_in-out_0ms]
---
 src/Classh/Box.hs            | 16 +---------------
 src/Classh/Box/Transition.hs |  4 ++--
 src/Classh/Class/SetSides.hs |  3 ++-
 src/Classh/Setters.hs        |  4 ++--
 src/Classh/WithTransition.hs | 35 +++++++++++++++++++++++++++++------
 5 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/src/Classh/Box.hs b/src/Classh/Box.hs
index 22a041e..e2fcbdd 100644
--- a/src/Classh/Box.hs
+++ b/src/Classh/Box.hs
@@ -66,7 +66,6 @@ module Classh.Box
   , border
   , position
   , shadow
-  , transition
   , box_custom
   ) where
 
@@ -105,8 +104,6 @@ data BoxConfig = BoxConfig
   , _border :: BorderConfig -- { rounded, thickness, etc .. }
   , _position :: WhenTW (Justify, Align)
   , _shadow :: WhenTW (WithTransition BoxShadow)  -- Transitionable!
-  , _transition :: TransitionConfigGlobal  -- Global transition (legacy support)
-  --, _text_align :: Align ... or should we set == position.align
   , _box_custom :: T.Text
   }
   deriving Show
@@ -117,7 +114,7 @@ makeLenses ''BoxConfig
 ------------  Defaults of Records
 
 instance Default BoxConfig where
-  def = BoxConfig def def def def def def def def def def def ""
+  def = BoxConfig def def def def def def def def def def ""
 
 
 instance CompileStyle BoxConfig where
@@ -133,7 +130,6 @@ instance CompileStyle BoxConfig where
       , compileWithTransitionTW (_bgColor cfg) ((<>) "bg-" . showTW) Transition_Colors
       , compileWithTransitionTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow) Transition_Opacity
       , compileWithTransitionTW (_shadow cfg) showTW Transition_Shadow
-      , compileTransitionGlobal (_transition cfg)
       , Right $ _box_custom cfg
       ]
       where
@@ -190,13 +186,6 @@ instance CompileStyle BoxConfig where
           , compileWithTransitionTW (_marginB cfg') ((<>) "mb-" . showTW) Transition_All
           ]
 
-        compileTransitionGlobal cfg' = pure . foldr (<&>) mempty =<< sequenceA
-          [ compileWhenTW (_transitionProperty cfg') showTW
-          , compileWhenTW (_transitionDurationGlobal cfg') showTW
-          , compileWhenTW (_transitionTimingGlobal cfg') showTW
-          , compileWhenTW (_transitionDelayGlobal cfg') showTW
-          ]
-
         compilePos posCfg = case f $ fmap fst posCfg of
           Left e -> Left e
           Right () -> Right $ foldr (<&>) mempty $ fmap
@@ -229,8 +218,6 @@ instance ShowTW BoxConfig where
         in prefix <> "grid" <&> prefix <> (showTW jus) <&> prefix <> (showTW align)
      ) $ _position cfg
    , renderWithTransitionTW (_shadow cfg) showTW Transition_Shadow
-   , showTW . _transition $ cfg
-   --, renderWhenTW (_position cfg) $ \(j,a) -> "grid " <> showTW j <> " " <> showTW a
    , _box_custom cfg
    ]
 
@@ -249,6 +236,5 @@ instance Semigroup BoxConfig where
     , _border     = _border a   <> _border b
     , _position   = _position a <> _position b
     , _shadow     = _shadow a <> _shadow b
-    , _transition = _transition a <> _transition b
     , _box_custom = _box_custom a <> _box_custom b
     }
diff --git a/src/Classh/Box/Transition.hs b/src/Classh/Box/Transition.hs
index 0accee6..cab5b1c 100644
--- a/src/Classh/Box/Transition.hs
+++ b/src/Classh/Box/Transition.hs
@@ -116,7 +116,7 @@ instance ShowTW TransitionProperty where
   showTW = \case
     Transition -> "transition"
     Transition_Custom val -> "transition-[" <> val <> "]"
-    other -> T.toLower (tshow other)
+    other -> T.replace "_" "-" $ T.toLower (tshow other)
 
 -- Instances for TransitionDuration
 instance Default TransitionDuration where
@@ -135,7 +135,7 @@ instance Default TransitionTimingFunction where
 instance ShowTW TransitionTimingFunction where
   showTW = \case
     Ease_Custom val -> "ease-[" <> val <> "]"
-    other -> T.toLower (tshow other)
+    other -> T.replace "_" "-" $ T.toLower (tshow other)
 
 -- Instances for TransitionDelay
 instance Default TransitionDelay where
diff --git a/src/Classh/Class/SetSides.hs b/src/Classh/Class/SetSides.hs
index 9986639..bd8982f 100644
--- a/src/Classh/Class/SetSides.hs
+++ b/src/Classh/Class/SetSides.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE MultiParamTypeClasses #-}
+{-# LANGUAGE FunctionalDependencies #-}
 
 module Classh.Class.SetSides where
 
@@ -7,7 +8,7 @@ import Control.Lens
 
 -- | This class allows for shorthand for a config that is based on sides, such
 -- | as padding or margin or border
-class SetSides tw a where
+class SetSides tw a | tw -> a where
   x :: Lens' tw (WhenTW a)
   y :: Lens' tw (WhenTW a)
   xy :: Lens' tw (WhenTW a)
diff --git a/src/Classh/Setters.hs b/src/Classh/Setters.hs
index 5d61484..762488b 100644
--- a/src/Classh/Setters.hs
+++ b/src/Classh/Setters.hs
@@ -67,7 +67,7 @@ infixr 4 .~~
 class SetConstant field where
   (.~~) :: ASetter s t c (WhenTW field) -> UnwrapType field -> s -> t
 
-instance SetConstant (WithTransition a) where
+instance {-# OVERLAPPING #-} SetConstant (WithTransition a) where
   someLens .~~ newVals = over someLens (const $ only $ noTransition newVals)
 
 instance {-# OVERLAPPABLE #-} (UnwrapType a ~ a) => SetConstant a where
@@ -101,7 +101,7 @@ instance {-# OVERLAPPABLE #-} (UnwrapType a ~ a) => AddResponsive a where
 
 -- | Both are functions from Classh with changed infix precedence to work with <>
 infixr 7 .-
-(.-) :: SetConstant a => ASetter s t c (WhenTW a) -> UnwrapType a -> s -> t
+(.-) :: SetConstant field => ASetter s t c (WhenTW field) -> UnwrapType field -> s -> t
 (.-) = (.~~)
 
 infixr 7 .|<~
diff --git a/src/Classh/WithTransition.hs b/src/Classh/WithTransition.hs
index 0285ba4..d3875f1 100644
--- a/src/Classh/WithTransition.hs
+++ b/src/Classh/WithTransition.hs
@@ -33,9 +33,9 @@
 module Classh.WithTransition where
 
 import Classh.Box.Transition
-import Classh.Class.ShowTW
 import Classh.Responsive.WhenTW
 import Classh.Internal.Chain
+import Classh.Internal.TShow (tshow)
 import Data.Default
 import qualified Data.Text as T
 
@@ -105,14 +105,37 @@ renderWithTransitionTW tws construct prop = foldr (<&>) mempty $
         transitionClasses = case mTransCfg of
           Nothing -> mempty
           Just cfg ->
-            let transProp = prefix <> showTW prop
-                transDur = prefix <> showTW (_transitionDuration cfg)
-                transTiming = prefix <> showTW (_transitionTiming cfg)
-                transDelay = prefix <> showTW (_transitionDelay cfg)
-            in transProp <&> transDur <&> transTiming <&> transDelay
+            let cssProp = transitionPropertyToCSSName prop
+                duration = T.drop 9 $ tshow (_transitionDuration cfg)  -- Remove "Duration_" prefix
+                timing = transitionTimingToCSSName (_transitionTiming cfg)
+                delay = T.drop 6 $ tshow (_transitionDelay cfg)  -- Remove "Delay_" prefix
+                -- Format: [transition:property_duration_timing_delay]
+                transValue = cssProp <> "_" <> duration <> "ms_" <> timing <> "_" <> delay <> "ms"
+            in prefix <> "[transition:" <> transValue <> "]"
     in valueClass <&> transitionClasses
   ) tws
 
+-- | Convert TransitionProperty to CSS property name for arbitrary value syntax
+transitionPropertyToCSSName :: TransitionProperty -> T.Text
+transitionPropertyToCSSName = \case
+  Transition_None -> "none"
+  Transition_All -> "all"
+  Transition -> "all"  -- Default transition affects all properties
+  Transition_Colors -> "background-color,border-color,color,fill,stroke"
+  Transition_Opacity -> "opacity"
+  Transition_Shadow -> "box-shadow"
+  Transition_Transform -> "transform"
+  Transition_Custom val -> val
+
+-- | Convert TransitionTimingFunction to CSS timing function name
+transitionTimingToCSSName :: TransitionTimingFunction -> T.Text
+transitionTimingToCSSName = \case
+  Ease_Linear -> "linear"
+  Ease_In -> "in"
+  Ease_Out -> "out"
+  Ease_InOut -> "in-out"
+  Ease_Custom val -> val
+
 -- | Helper for compiling WithTransition values (with duplicate checking)
 compileWithTransitionTW :: WhenTW (WithTransition a)
                         -> (a -> T.Text)

From 85a6908970220084ba82a6cc4f0008e7e55de169 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 21:37:32 -0500
Subject: [PATCH 14/29] test: add comprehensive transition test suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add TransitionTest.hs with 4 transition pattern tests
- Add ComprehensiveTest.hs with 11 property tests covering all ClasshSS features
- Add GenerateHTMLTest.hs with visual HTML generation for browser testing
- Add 10+ unique transition configurations across 6 responsive breakpoints
- Include tests for: durations (75ms-1000ms), timing functions (linear/ease-in/ease-out/ease-in-out), delays (0ms-1000ms)
- Generate test-output.html with rainbow spectrum (Red→Orange→Yellow→Green→Blue→Purple) for easy visual verification
- Automatically opens generated HTML in Chrome for manual testing

All tests pass (15/15 total) and verify the arbitrary transition syntax works correctly.
---
 ClasshSS.cabal            |  37 +++++++
 test/ComprehensiveTest.hs | 216 ++++++++++++++++++++++++++++++++++++++
 test/GenerateHTMLTest.hs  | 203 +++++++++++++++++++++++++++++++++++
 test/TransitionTest.hs    |  94 ++++++++++++-----
 4 files changed, 525 insertions(+), 25 deletions(-)
 create mode 100644 test/ComprehensiveTest.hs
 create mode 100644 test/GenerateHTMLTest.hs

diff --git a/ClasshSS.cabal b/ClasshSS.cabal
index 7ba1d4a..f425e37 100644
--- a/ClasshSS.cabal
+++ b/ClasshSS.cabal
@@ -116,3 +116,40 @@ library
     hs-source-dirs:   src
     ghc-options: -Wall -Werror -O -threaded -fno-show-valid-hole-fits
     default-language: Haskell2010
+
+test-suite transition-test
+    import:           warnings
+    type:             exitcode-stdio-1.0
+    hs-source-dirs:   test
+    main-is:          TransitionTest.hs
+    build-depends:    base
+                    , ClasshSS
+                    , data-default
+                    , lens
+                    , text
+    default-language: Haskell2010
+
+test-suite comprehensive-test
+    import:           warnings
+    type:             exitcode-stdio-1.0
+    hs-source-dirs:   test
+    main-is:          ComprehensiveTest.hs
+    build-depends:    base
+                    , ClasshSS
+                    , data-default
+                    , lens
+                    , text
+    default-language: Haskell2010
+
+test-suite generate-html-test
+    import:           warnings
+    type:             exitcode-stdio-1.0
+    hs-source-dirs:   test
+    main-is:          GenerateHTMLTest.hs
+    build-depends:    base
+                    , ClasshSS
+                    , data-default
+                    , lens
+                    , text
+                    , process
+    default-language: Haskell2010
diff --git a/test/ComprehensiveTest.hs b/test/ComprehensiveTest.hs
new file mode 100644
index 0000000..5e84f43
--- /dev/null
+++ b/test/ComprehensiveTest.hs
@@ -0,0 +1,216 @@
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module Main where
+
+import Classh
+import Classh.Box
+import Classh.Box.Padding
+import Classh.Box.Margin
+import Classh.Box.Border
+import Classh.Box.Shadow
+import Classh.Box.Placement
+import Classh.Box.TWSize
+import Classh.Box.SizingBand
+import Classh.Color
+import Classh.Box.Transition
+import Classh.WithTransition
+import Classh.Setters
+import Classh.Class.CompileStyle
+import Classh.Class.SetSides
+import Classh.Text
+import Control.Lens ((&))
+import Data.Default (def)
+import qualified Data.Text as T
+
+-- Box property tests
+testBoxBasics :: BoxConfig
+testBoxBasics = def
+  & colStart .~~ 1
+  & colSpan .~~ 6
+  & bgColor .~~ Blue C500
+  & bgOpacity .~~ 80
+
+-- Responsive properties with .|~
+testResponsive :: BoxConfig
+testResponsive = def
+  & bgColor .|~ [Gray C100, Gray C200, Gray C300, Gray C400, Gray C500, Gray C600]
+
+-- Padding with SetSides shorthand
+testPaddingSetSides :: BoxConfig
+testPaddingSetSides = def
+  & padding . b .~~ TWSize 4
+  & padding . t .~~ TWSize 8
+  & padding . x .~~ TWSize 2
+
+-- Padding with transitions
+testPaddingTransitions :: BoxConfig
+testPaddingTransitions = def
+  & padding . paddingB .~^ [ ("def", noTransition (TWSize 4))
+                            , ("hover", TWSize 8 `withTransition` Duration_300)
+                            ]
+
+-- Margin tests
+testMargin :: BoxConfig
+testMargin = def
+  & margin . marginL .~~ TWSize 2
+  & margin . marginR .~~ TWSize 2
+  & margin . y .~~ TWSize 4
+
+-- Border tests
+testBorder :: BoxConfig
+testBorder = def
+  & border . bWidth . b .~~ B2
+  & border . bColor . allS .~~ Red C500
+  & border . radius . borderRadius_tr .~~ R_Lg
+
+-- Border with transitions
+testBorderTransitions :: BoxConfig
+testBorderTransitions = def
+  & border . bColor . allS .~^ [ ("def", noTransition (Blue C500))
+                                , ("hover", Red C500 `withTransition` Duration_200)
+                                ]
+
+-- Shadow tests
+testShadow :: BoxConfig
+testShadow = def
+  & shadow .~~ Shadow_Lg
+
+-- Shadow with transitions
+testShadowTransitions :: BoxConfig
+testShadowTransitions = def
+  & shadow .~^ [ ("def", noTransition Shadow_Sm)
+                , ("hover", Shadow_Xl `withTransition` Duration_300)
+                ]
+
+-- Position tests
+testPosition :: BoxConfig
+testPosition = def
+  & position .~~ (J_Center, A_Center)
+
+-- Sizing tests - TODO: Fix lens composition issue
+-- testSizing :: BoxConfig
+-- testSizing = def
+--   & (sizingBand . w) .~~ TWSize 64
+--   & (sizingBand . h) .~~ TWSize 32
+--   & (sizingBand . maxW) .~~ TWSize_Screen
+
+-- Combined complex test
+testComplex :: BoxConfig
+testComplex = def
+  & bgColor .~^ [ ("def", noTransition (Blue C600))
+                , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                ]
+  & padding . x .~~ TWSize 4
+  & padding . y .~~ TWSize 2
+  & border . radius . allS .~~ R_Md
+  & shadow .~^ [ ("def", noTransition Shadow_None)
+                , ("hover", Shadow_Lg `withTransition` Duration_200)
+                ]
+
+-- Text tests - TODO: Add Show instance for TextConfigTW
+-- testText :: TextConfigTW
+-- testText = def
+--   & text_size .~~ XL
+--   & text_weight .~~ Bold
+--   & text_color .~~ White
+
+testCase :: (CompileStyle a, Show a) => String -> a -> T.Text -> IO Bool
+testCase name cfg expected = do
+  putStrLn $ "\n" ++ replicate 80 '-'
+  putStrLn $ "TEST: " ++ name
+  putStrLn $ replicate 80 '-'
+  case compileS cfg of
+    Left err -> do
+      putStrLn $ "❌ ERROR: " ++ show err
+      return False
+    Right result -> do
+      let success = result == expected
+      putStrLn $ "Output:"
+      putStrLn $ "  " ++ show result
+      putStrLn ""
+      if success
+        then putStrLn "✓ PASS"
+        else do
+          putStrLn "✗ FAIL"
+          putStrLn $ "\nExpected:"
+          putStrLn $ "  " ++ show expected
+      return success
+
+main :: IO ()
+main = do
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                    ClasshSS Comprehensive Test Suite"
+  putStrLn $ replicate 80 '='
+
+  results <- sequenceA
+    [ testCase "Box basics (colStart, colSpan, bgColor, bgOpacity)"
+        testBoxBasics
+        "col-start-1 col-span-6 bg-blue-500 bg-opacity-80"
+
+    , testCase "Responsive bgColor (.|~)"
+        testResponsive
+        "bg-gray-100 sm:bg-gray-200 md:bg-gray-300 lg:bg-gray-400 xl:bg-gray-500 2xl:bg-gray-600"
+
+    , testCase "Padding with SetSides shorthand (b, t, x)"
+        testPaddingSetSides
+        "pl-2 pr-2 pt-8 pb-4"
+
+    , testCase "Padding with transitions"
+        testPaddingTransitions
+        "pb-4 hover:pb-8 hover:[transition:all_300ms_linear_0ms]"
+
+    , testCase "Margin (marginL, marginR, marginY)"
+        testMargin
+        "ml-2 mr-2 mt-4 mb-4"
+
+    , testCase "Border (width, color, radius)"
+        testBorder
+        "rounded-tr-lg border-b-2 border-l-red-500 border-r-red-500 border-t-red-500 border-b-red-500"
+
+    , testCase "Border color with transitions"
+        testBorderTransitions
+        "border-l-blue-500 hover:border-l-red-500 hover:[transition:background-color,border-color,color,fill,stroke_200ms_linear_0ms] border-r-blue-500 hover:border-r-red-500 hover:[transition:background-color,border-color,color,fill,stroke_200ms_linear_0ms] border-t-blue-500 hover:border-t-red-500 hover:[transition:background-color,border-color,color,fill,stroke_200ms_linear_0ms] border-b-blue-500 hover:border-b-red-500 hover:[transition:background-color,border-color,color,fill,stroke_200ms_linear_0ms]"
+
+    , testCase "Shadow"
+        testShadow
+        "shadow-lg"
+
+    , testCase "Shadow with transitions"
+        testShadowTransitions
+        "shadow-sm hover:shadow-xl hover:[transition:box-shadow_300ms_linear_0ms]"
+
+    , testCase "Position (center/center)"
+        testPosition
+        "grid justify-items-center content-center"
+
+    -- , testCase "Sizing (w, h, maxW)"
+    --     testSizing
+    --     "w-64 h-32 max-w-screen"
+
+    , testCase "Complex combined properties"
+        testComplex
+        "rounded-tr-md rounded-tl-md rounded-br-md rounded-bl-md pl-4 pr-4 pt-2 pb-2 bg-blue-600 hover:bg-blue-400 hover:[transition:background-color,border-color,color,fill,stroke_300ms_in-out_0ms] shadow-none hover:shadow-lg hover:[transition:box-shadow_200ms_linear_0ms]"
+
+    -- , testCase "Text (size, weight, color)"
+    --     testText
+    --     "text-xl font-bold text-white"
+    ]
+
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                              SUMMARY"
+  putStrLn $ replicate 80 '='
+  let passed = length $ filter id results
+      total = length results
+  putStrLn $ "Tests passed: " ++ show passed ++ "/" ++ show total
+  putStrLn ""
+
+  if and results
+    then do
+      putStrLn "✓ ALL TESTS PASSED!"
+      putStrLn $ replicate 80 '='
+    else do
+      putStrLn "✗ SOME TESTS FAILED"
+      putStrLn $ replicate 80 '='
diff --git a/test/GenerateHTMLTest.hs b/test/GenerateHTMLTest.hs
new file mode 100644
index 0000000..5b44231
--- /dev/null
+++ b/test/GenerateHTMLTest.hs
@@ -0,0 +1,203 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module Main where
+
+import Classh
+import Classh.Box
+import Classh.Box.Padding
+import Classh.Box.Margin
+import Classh.Box.Border
+import Classh.Box.Shadow
+import Classh.Color
+import Classh.Box.Transition
+import Classh.WithTransition
+import Classh.Setters
+import Classh.Class.CompileStyle
+import Classh.Class.SetSides
+import Control.Lens ((&))
+import Data.Default (def)
+import qualified Data.Text as T
+import Data.Either (fromRight)
+import System.Process (rawSystem)
+
+-- Test configurations
+tests :: [(String, BoxConfig, String)]
+tests =
+  [ ("Background Color - Hover + Focus + Active", testBgAllStates, "Hover (blue), Focus (green), Click (red)")
+  , ("Border Color - Hover + Focus + Active", testBorderAllStates, "Hover (purple border), Focus (yellow border), Click (pink border)")
+  , ("Combined Bg + Border - All States", testCombined, "Both background and border should transition")
+  , ("Responsive Breakpoints", testResponsive, "Resize window to see color change at breakpoints")
+  , ("Shadow Transitions", testShadow, "Hover to see shadow transition")
+  , ("Complex Combined", testComplex, "Background, border, shadow, and padding all transition")
+
+  -- Comprehensive transition tests
+  , ("Comprehensive Responsive Transitions", testComprehensiveResponsiveTransitions,
+     "Resize window through ALL breakpoints (640px, 768px, 1024px, 1280px, 1536px). Each has unique transition timing! Hover for pink, focus for cyan.")
+  , ("Stacked Transitions (Responsive + Hover)", testStackedTransitions,
+     "Resize AND hover - see how responsive + interactive transitions combine with border color")
+  , ("Delay Showcase", testDelayShowcase,
+     "Compare delays: Hover (500ms wait) vs Focus (1000ms wait)")
+  , ("Speed Comparison", testSpeedComparison,
+     "Lightning fast (75ms) vs slow motion (1000ms)")
+  ]
+
+testBgAllStates :: BoxConfig
+testBgAllStates = def
+  & bgColor .~^ [ ("def", noTransition (Gray C500))
+                , ("hover", Blue C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                , ("focus", Green C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                ]
+
+testBorderAllStates :: BoxConfig
+testBorderAllStates = def
+  & border . bWidth . allS .~~ B4
+  & border . bColor . allS .~^ [ ("def", noTransition (Gray C400))
+                                , ("hover", Purple C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                                , ("focus", Yellow C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                                ]
+
+testCombined :: BoxConfig
+testCombined = def
+  & bgColor .~^ [ ("def", noTransition (Blue C600))
+                , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                , ("focus", Green C600 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                ]
+  & border . bWidth . allS .~~ B4
+  & border . bColor . allS .~^ [ ("def", noTransition (Blue C800))
+                                , ("hover", Blue C600 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                                , ("focus", Green C800 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                                ]
+
+testResponsive :: BoxConfig
+testResponsive = def
+  & bgColor .|~ [ Gray C800, Red C600, Orange C600, Yellow C600, Green C600, Blue C600 ]
+
+testShadow :: BoxConfig
+testShadow = def
+  & shadow .~^ [ ("def", noTransition Shadow_Sm)
+                , ("hover", Shadow_Xl `withTransition` Duration_300)
+                ]
+
+testComplex :: BoxConfig
+testComplex = def
+  & bgColor .~^ [ ("def", noTransition (Blue C600))
+                , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                ]
+  & padding . x .~~ TWSize 4
+  & padding . y .~~ TWSize 2
+  & border . radius . allS .~~ R_Md
+  & shadow .~^ [ ("def", noTransition Shadow_None)
+                , ("hover", Shadow_Lg `withTransition` Duration_200)
+                ]
+
+-- Comprehensive test: All 6 responsive breakpoints with unique transitions
+testComprehensiveResponsiveTransitions :: BoxConfig
+testComprehensiveResponsiveTransitions = def
+  & bgColor .~^
+    [ ("def",   Red C600    `withTransition` Duration_500  `withTiming` Ease_Linear `withDelay` Delay_0)
+    , ("sm",    Orange C600 `withTransition` Duration_300  `withTiming` Ease_In     `withDelay` Delay_100)
+    , ("md",    Yellow C600 `withTransition` Duration_700  `withTiming` Ease_Out    `withDelay` Delay_150)
+    , ("lg",    Green C600  `withTransition` Duration_200  `withTiming` Ease_InOut  `withDelay` Delay_0)
+    , ("xl",    Blue C600   `withTransition` Duration_1000 `withTiming` Ease_Linear `withDelay` Delay_300)
+    , ("2xl",   Purple C600 `withTransition` Duration_500  `withTiming` Ease_InOut  `withDelay` Delay_75)
+    , ("hover", Pink C400   `withTransition` Duration_150  `withTiming` Ease_Out    `withDelay` Delay_0)
+    , ("focus", Cyan C400   `withTransition` Duration_300  `withTiming` Ease_InOut  `withDelay` Delay_200)
+    ]
+
+testStackedTransitions :: BoxConfig
+testStackedTransitions = def
+  & bgColor .~^
+    [ ("def",   Gray C800   `withTransition` Duration_300 `withTiming` Ease_Linear)
+    , ("sm",    Gray C700   `withTransition` Duration_300 `withTiming` Ease_In)
+    , ("hover", Green C500  `withTransition` Duration_200 `withTiming` Ease_Out)
+    ]
+  & border . bWidth . allS .~~ B2
+  & border . bColor . allS .~^
+    [ ("def",   Gray C600   `withTransition` Duration_300)
+    , ("hover", Green C400  `withTransition` Duration_200)
+    ]
+
+testDelayShowcase :: BoxConfig
+testDelayShowcase = def
+  & bgColor .~^
+    [ ("def",   Blue C600 `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_0)
+    , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_500)
+    , ("focus", Blue C200 `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_1000)
+    ]
+
+testSpeedComparison :: BoxConfig
+testSpeedComparison = def
+  & bgColor .~^
+    [ ("def",   Purple C600 `withTransition` Duration_75   `withTiming` Ease_Linear)
+    , ("hover", Purple C400 `withTransition` Duration_1000 `withTiming` Ease_Linear)
+    ]
+
+generateHTML :: IO ()
+generateHTML = do
+  let htmlHeader = T.unlines
+        [ "<!DOCTYPE html>"
+        , "<html lang=\"en\">"
+        , "<head>"
+        , "    <meta charset=\"UTF-8\">"
+        , "    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">"
+        , "    <title>ClasshSS Transition Tests</title>"
+        , "    <script src=\"https://cdn.tailwindcss.com\"></script>"
+        , "    <style>"
+        , "        .test-section { margin-bottom: 2rem; padding: 1.5rem; border: 2px solid #e5e7eb; border-radius: 0.5rem; }"
+        , "        .code-block { background: #1e1e1e; color: #d4d4d4; padding: 0.75rem; border-radius: 0.375rem; font-family: monospace; font-size: 0.75rem; overflow-x: auto; margin-bottom: 0.75rem; }"
+        , "        .screen-indicator { position: fixed; top: 1rem; right: 1rem; background: black; color: white; padding: 0.5rem 1rem; border-radius: 0.375rem; font-weight: bold; z-index: 1000; }"
+        , "    </style>"
+        , "</head>"
+        , "<body class=\"bg-gray-50 p-8\">"
+        , "    <div class=\"screen-indicator\">"
+        , "        <span class=\"sm:hidden\">Base (&lt;640px)</span>"
+        , "        <span class=\"hidden sm:inline md:hidden\">SM (≥640px)</span>"
+        , "        <span class=\"hidden md:inline lg:hidden\">MD (≥768px)</span>"
+        , "        <span class=\"hidden lg:inline xl:hidden\">LG (≥1024px)</span>"
+        , "        <span class=\"hidden xl:inline 2xl:hidden\">XL (≥1280px)</span>"
+        , "        <span class=\"hidden 2xl:inline\">2XL (≥1536px)</span>"
+        , "    </div>"
+        , "    <div class=\"max-w-6xl mx-auto\">"
+        , "        <h1 class=\"text-4xl font-bold mb-8 text-gray-900\">ClasshSS Generated Transition Tests</h1>"
+        ]
+
+  let htmlFooter = T.unlines
+        [ "        <div class=\"mt-8 p-6 bg-blue-50 border-l-4 border-blue-500 rounded-lg\">"
+        , "            <h3 class=\"text-xl font-semibold mb-3 text-blue-900\">Instructions:</h3>"
+        , "            <ul class=\"list-disc list-inside space-y-2 text-blue-800\">"
+        , "                <li>Hover over each box to test transitions</li>"
+        , "                <li>Tab or click to focus boxes (green state)</li>"
+        , "                <li>Resize window to test responsive breakpoints</li>"
+        , "                <li>Check if transitions are smooth or instant</li>"
+        , "            </ul>"
+        , "        </div>"
+        , "    </div>"
+        , "</body>"
+        , "</html>"
+        ]
+
+  let testSections = map generateTestSection tests
+  let fullHTML = htmlHeader <> T.concat testSections <> htmlFooter
+
+  writeFile "test-output.html" (T.unpack fullHTML)
+  putStrLn "Generated test-output.html"
+
+generateTestSection :: (String, BoxConfig, String) -> T.Text
+generateTestSection (name, cfg, description) =
+  let classes = fromRight "ERROR" (compileS cfg)
+  in T.unlines
+    [ "        <div class=\"test-section\">"
+    , "            <h2 class=\"text-2xl font-semibold mb-3\">" <> T.pack name <> "</h2>"
+    , "            <div class=\"code-block\">" <> classes <> "</div>"
+    , "            <div class=\"" <> classes <> " p-6 text-white text-center rounded-lg cursor-pointer\">"
+    , "                " <> T.pack description
+    , "            </div>"
+    , "        </div>"
+    ]
+
+main :: IO ()
+main = do
+  generateHTML
+  putStrLn "Opening in Chrome..."
+  _ <- rawSystem "google-chrome-stable" ["test-output.html"]
+  return ()
diff --git a/test/TransitionTest.hs b/test/TransitionTest.hs
index 6f5e169..328ec9c 100644
--- a/test/TransitionTest.hs
+++ b/test/TransitionTest.hs
@@ -5,11 +5,16 @@ module Main where
 
 import Classh
 import Classh.Box
+import Classh.Box.Padding
 import Classh.Color
 import Classh.Box.Transition
 import Classh.WithTransition
 import Classh.Setters
 import Classh.Class.CompileStyle
+import Classh.Class.SetSides
+import Control.Lens ((&))
+import Data.Default (def)
+import qualified Data.Text as T
 
 -- Test 1: Backwards compatible - no transitions
 test1 :: BoxConfig
@@ -27,37 +32,76 @@ test2 = def
 -- Test 3: Builder pattern with chaining
 test3 :: BoxConfig
 test3 = def
-  & bgColor .~^ [ ("def", noTransition Purple)
-                , ("hover", Lavender `withTransition` Duration_300 `withTiming` Ease_InOut)
-                , ("focus", Indigo `withTransition` Duration_500 `withTiming` Ease_Out `withDelay` Delay_100)
+  & bgColor .~^ [ ("def", noTransition (Purple C600))
+                , ("hover", (Purple C300) `withTransition` Duration_300 `withTiming` Ease_InOut)
+                , ("focus", (Indigo C500) `withTransition` Duration_500 `withTiming` Ease_Out `withDelay` Delay_100)
                 ]
 
 -- Test 4: All-at-once style
 test4 :: BoxConfig
 test4 = def
-  & bgColor .~^ [ ("def", noTransition Purple)
-                , ("sm", Indigo `withTransitionAll` Duration_300 Ease_InOut Delay_0)
-                , ("hover", Lavender `withTransition` Duration_500)
+  & bgColor .~^ [ ("def", noTransition (Purple C600))
+                , ("sm", withTransitionAll (Indigo C500) Duration_300 Ease_InOut Delay_0)
+                , ("hover", (Purple C300) `withTransition` Duration_500)
                 ]
 
+testCase :: String -> BoxConfig -> T.Text -> IO Bool
+testCase name cfg expected = do
+  putStrLn $ "\n" ++ replicate 80 '-'
+  putStrLn $ "TEST: " ++ name
+  putStrLn $ replicate 80 '-'
+  case compileS cfg of
+    Left err -> do
+      putStrLn $ "❌ ERROR: " ++ show err
+      return False
+    Right result -> do
+      let success = result == expected
+      putStrLn $ "Output:"
+      putStrLn $ "  " ++ show result
+      putStrLn ""
+      if success
+        then putStrLn "✓ PASS"
+        else do
+          putStrLn "✗ FAIL"
+          putStrLn $ "\nExpected:"
+          putStrLn $ "  " ++ show expected
+      return success
+
 main :: IO ()
 main = do
-  putStrLn "Test 1 (backwards compatible):"
-  case compileS test1 of
-    Left err -> putStrLn $ "Error: " ++ show err
-    Right result -> putStrLn $ "  " ++ show result
-
-  putStrLn "\nTest 2 (hover with transition):"
-  case compileS test2 of
-    Left err -> putStrLn $ "Error: " ++ show err
-    Right result -> putStrLn $ "  " ++ show result
-
-  putStrLn "\nTest 3 (builder pattern with chaining):"
-  case compileS test3 of
-    Left err -> putStrLn $ "Error: " ++ show err
-    Right result -> putStrLn $ "  " ++ show result
-
-  putStrLn "\nTest 4 (all-at-once style):"
-  case compileS test4 of
-    Left err -> putStrLn $ "Error: " ++ show err
-    Right result -> putStrLn $ "  " ++ show result
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                       Transition Feature Test Suite"
+  putStrLn $ replicate 80 '='
+
+  results <- sequenceA
+    [ testCase "Test 1 (backwards compatible)"
+        test1
+        "col-span-2 bg-gray-500"
+    , testCase "Test 2 (hover with transition)"
+        test2
+        "bg-gray-500 hover:bg-gray-300 hover:[transition:background-color,border-color,color,fill,stroke_300ms_linear_0ms]"
+    , testCase "Test 3 (builder pattern with chaining)"
+        test3
+        "bg-purple-600 hover:bg-purple-300 hover:[transition:background-color,border-color,color,fill,stroke_300ms_in-out_0ms] focus:bg-indigo-500 focus:[transition:background-color,border-color,color,fill,stroke_500ms_out_100ms]"
+    , testCase "Test 4 (all-at-once style)"
+        test4
+        "bg-purple-600 sm:bg-indigo-500 sm:[transition:background-color,border-color,color,fill,stroke_300ms_in-out_0ms] hover:bg-purple-300 hover:[transition:background-color,border-color,color,fill,stroke_500ms_linear_0ms]"
+    ]
+
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                              SUMMARY"
+  putStrLn $ replicate 80 '='
+  let passed = length $ filter id results
+      total = length results
+  putStrLn $ "Tests passed: " ++ show passed ++ "/" ++ show total
+  putStrLn ""
+
+  if and results
+    then do
+      putStrLn "✓ ALL TESTS PASSED!"
+      putStrLn $ replicate 80 '='
+    else do
+      putStrLn "✗ SOME TESTS FAILED"
+      putStrLn $ replicate 80 '='

From 300eecf59b852115c841ee17944fc8ee7d3329fe Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 21:39:07 -0500
Subject: [PATCH 15/29] chore: ignore generated test HTML files

---
 .gitignore | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.gitignore b/.gitignore
index ec34490..c489add 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,7 @@ cabal.project.local~
 db*
 *.DS_Store
 static.out
+
+# Generated test files
+test-output.html
+test-transition.html

From c6b9bda4c57993c769c28da092c65a9d2d1a5748 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Feb 2026 22:01:17 -0500
Subject: [PATCH 16/29] fix: remove Chrome auto-open from HTML test

The google-chrome-stable executable doesn't exist on all systems.
Now the test just generates the HTML file and prompts the user to open it manually.
---
 ClasshSS.cabal           | 1 -
 test/GenerateHTMLTest.hs | 5 +----
 2 files changed, 1 insertion(+), 5 deletions(-)

diff --git a/ClasshSS.cabal b/ClasshSS.cabal
index f425e37..05b6a2d 100644
--- a/ClasshSS.cabal
+++ b/ClasshSS.cabal
@@ -151,5 +151,4 @@ test-suite generate-html-test
                     , data-default
                     , lens
                     , text
-                    , process
     default-language: Haskell2010
diff --git a/test/GenerateHTMLTest.hs b/test/GenerateHTMLTest.hs
index 5b44231..476533a 100644
--- a/test/GenerateHTMLTest.hs
+++ b/test/GenerateHTMLTest.hs
@@ -18,7 +18,6 @@ import Control.Lens ((&))
 import Data.Default (def)
 import qualified Data.Text as T
 import Data.Either (fromRight)
-import System.Process (rawSystem)
 
 -- Test configurations
 tests :: [(String, BoxConfig, String)]
@@ -198,6 +197,4 @@ generateTestSection (name, cfg, description) =
 main :: IO ()
 main = do
   generateHTML
-  putStrLn "Opening in Chrome..."
-  _ <- rawSystem "google-chrome-stable" ["test-output.html"]
-  return ()
+  putStrLn "✓ Test complete! Open test-output.html in your browser to view."

From e6bedabcb834ea7b9a29164b5903fd5450e4c664 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Fri, 20 Feb 2026 14:23:52 -0500
Subject: [PATCH 17/29] feat: add complete transform support following Tailwind
 v3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive transform support to BoxConfig with all Tailwind v3 transform properties:

Transform properties added:
- Rotate: standard values (0°, 1°, 2°, 3°, 6°, 12°, 45°, 90°, 180°) + custom
- Scale: standard values (0, 50, 75, 90, 95, 100, 105, 110, 125, 150) + custom
- Translate: X/Y axes with TWSize values, fractions, px, full, and custom CSS sizes
- Skew: X/Y axes with standard values (0°, 1°, 2°, 3°, 6°, 12°) + custom
- Transform Origin: all 9 standard positions (center, corners, edges) + custom

All transforms support smooth transitions via withTransition, allowing animated
transform changes on hover, focus, and other states.

Changes:
- Add TransformConfig with all transform properties as fields
- Add transform field to BoxConfig
- Create comprehensive test suite (TransformTest.hs) with 15 tests
- Fix name collision with Control.Lens.transform by hiding it
- Fix variable shadowing in Classh.hs (transform -> mutation)
- Add -Wall -Werror to test suites for stricter compile-time checks
- Clean up unused imports in test files
- Update README with layout philosophy (no flexbox by design)

All tests pass (15/15 transform tests, plus existing test suites).
---
 ClasshSS.cabal              |  14 ++-
 README.md                   | 197 +++++++++++++++++++++++++++++++++++-
 src/Classh.hs               |   4 +-
 src/Classh/Box.hs           |  15 ++-
 src/Classh/Box/Transform.hs | 186 +++++++++++++++++++++++++++++++++-
 test/TransformTest.hs       | 186 ++++++++++++++++++++++++++++++++++
 test/TransitionTest.hs      |   7 --
 7 files changed, 591 insertions(+), 18 deletions(-)
 create mode 100644 test/TransformTest.hs

diff --git a/ClasshSS.cabal b/ClasshSS.cabal
index 05b6a2d..1b872c2 100644
--- a/ClasshSS.cabal
+++ b/ClasshSS.cabal
@@ -26,7 +26,7 @@ extra-doc-files:    CHANGELOG.md
 -- extra-source-files:
 
 common warnings
-    ghc-options: -Wall
+    ghc-options: -Wall -Werror
 
 library
     import:           warnings
@@ -152,3 +152,15 @@ test-suite generate-html-test
                     , lens
                     , text
     default-language: Haskell2010
+
+test-suite transform-test
+    import:           warnings
+    type:             exitcode-stdio-1.0
+    hs-source-dirs:   test
+    main-is:          TransformTest.hs
+    build-depends:    base
+                    , ClasshSS
+                    , data-default
+                    , lens
+                    , text
+    default-language: Haskell2010
diff --git a/README.md b/README.md
index cc37876..f7fcc51 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,195 @@
-# ClashSS
-typify CSS so that Style or Class tags do not overlap in obvious but easy to miss ways
+# ClasshSS
 
-Note: use Scrappy for bundled files and fetched files to further detect clashes
+Type-safe CSS-in-Haskell based on Tailwind CSS.
+
+## Overview
+
+ClasshSS lets you write Tailwind-style CSS in Haskell with compile-time checking. It prevents common mistakes like conflicting class definitions and ensures your styles are valid before runtime.
+
+Two main config types:
+- `BoxConfig` - element styling (layout, colors, borders, shadows)
+- `TextConfigTW` - text styling (font, size, weight, color)
+
+## Basic Example
+
+```haskell
+import Classh
+import Reflex.Dom.Core
+
+-- Box with styled text
+elClass "div" $(classh' [ pt .~~ TWSize 20, bgColor .~~ Gray C300 ]) $ do
+  textS $(classh' [text_size .|~ [XL, XL2]]) "Hello"
+```
+
+## Operators
+
+**`.~~`** - Set value for all screen sizes
+```haskell
+bgColor .~~ hex "281C40"
+br .~~ R_3Xl
+shadow .~~ Shadow_Md
+```
+
+**`.|~`** - Responsive values `[mobile, sm, md, lg, xl, 2xl]`
+```haskell
+w .|~ [TWSize 12, TWSize 24, TWSize 48]
+text_size .|~ [Base, LG, XL, XL2]
+```
+
+**`.~^`** - Stateful values (hover, focus, etc.) with transitions
+```haskell
+bgColor .~^ [("def", noTransition $ hex "281C40")
+           , ("hover", hex "7B4DF4" `withTransition` Duration_300)
+           ]
+```
+
+**`.~`** - Simple setter (mainly for `custom`)
+```haskell
+custom .~ "flex items-center"
+```
+
+## Common Properties
+
+### Box (BoxConfig)
+
+```haskell
+-- Spacing
+pt, pb, pl, pr, px, py, p      -- padding
+mt, mb, ml, mr, mx, my, m      -- margin
+
+-- Sizing
+w, h                            -- width, height
+minW, maxW, minH, maxH         -- constraints
+
+-- Border
+br, bw, bc                     -- radius, width, color
+br_t, br_b, br_l, br_r         -- individual corners
+
+-- Colors
+bgColor                        -- background
+bc                             -- border color
+
+-- Layout
+pos                            -- position (justify, align)
+colStart, colSpan              -- grid columns
+
+-- Visual
+shadow                         -- box shadow
+```
+
+### Text (TextConfigTW)
+
+```haskell
+text_size                      -- XS, SM, Base, LG, XL, XL2, XL3, etc.
+text_color                     -- any Color
+text_weight                    -- Light, Normal, Medium, Semibold, Bold, etc.
+text_font                      -- Font_Sans, Font_Serif, Font_Custom "Name"
+text_align                     -- Left, Center, Right, Justify
+```
+
+## Shorthand
+
+Instead of `border . radius . allS`, use `br`:
+```haskell
+$(classh' [ br .~~ R_3Xl
+          , bw .~~ B2
+          , bc .~~ hex "7B4DF4"
+          ])
+```
+
+## Colors
+
+```haskell
+-- Hex colors
+hex "281C40"
+
+-- Tailwind colors
+Gray C300
+Red C500
+Blue C600
+
+-- Standard
+White
+Black
+```
+
+## Transitions
+
+```haskell
+-- Basic
+bgColor .~^ [("def", noTransition purple)
+           , ("hover", lavender `withTransition` Duration_300)
+           ]
+
+-- With timing
+shadow .~^ [("def", noTransition Shadow_Md)
+          , ("hover", Shadow_Lg `withTransition` Duration_300
+                                `withTiming` Ease_InOut)
+          ]
+
+-- All at once
+bgColor .~^ [("def", noTransition blue)
+           , ("hover", purple `withTransitionAll` Duration_300 Ease_In Delay_0)
+           ]
+```
+
+## Template Haskell
+
+**`classh'`** - Compile with defaults
+```haskell
+$(classh' [ bgColor .~~ hex "281C40" ])
+```
+
+**`classh`** - Compile with custom base config
+```haskell
+$(classh myBaseConfig [ text_size .~~ XL2 ])
+```
+
+**`classhUnsafe`** - Runtime (no TH, for library functions)
+```haskell
+classhUnsafe [ bgColor .~~ hex "281C40" ]
+```
+
+The TH versions check for conflicts at compile-time. For example, setting both `pt` and `py` will fail to compile since they overlap.
+
+## Usage with Reflex
+
+```haskell
+-- Static classes
+elClass "div" $(classh' [ w .~~ TWSize_Full, p .~~ TWSize 4 ]) $
+  text "content"
+
+-- Dynamic classes
+dynClasses <- holdDyn (classhUnsafe [bgColor .~~ Gray C300]) $ ...
+elDynClass "div" dynClasses $ text "content"
+
+-- Text with styling
+textS $(classh' [ text_size .~~ XL3
+                , text_color .~~ hex "F3F1F8"
+                , text_weight .~~ Bold
+                ]) "Hello"
+```
+
+## Why ClasshSS?
+
+- **Type safety** - Invalid CSS won't compile
+- **No conflicts** - Can't accidentally set overlapping properties
+- **Responsive by default** - Easy to write mobile-first styles
+- **Transitions built-in** - Type-safe hover/focus states
+- **Tailwind familiar** - If you know Tailwind, you know ClasshSS
+- **Explicit layout** - Strict about width/height consumption, no flexbox magic
+
+## Layout Philosophy
+
+ClasshSS intentionally does NOT support `display: flex` or flexbox properties. The design philosophy is to be incredibly strict about layout and make it easy to see how each element "consumes" width or height from the page in a responsive, declarative manner.
+
+For layouts requiring flex, use the `custom` field:
+```haskell
+custom .~ "flex flex-col items-center"
+```
+
+This keeps layout behavior explicit and separate from the type-safe styling that ClasshSS provides.
+
+## License
+
+BSD-style
diff --git a/src/Classh.hs b/src/Classh.hs
index 204c891..282ad33 100644
--- a/src/Classh.hs
+++ b/src/Classh.hs
@@ -202,10 +202,10 @@ classhUnsafe muts = showTW $ def `applyFs` muts
 
 --classhV, classhV' :: Q Exp
 classhV :: (CompileStyle a) => a -> (a -> a) -> Q Exp
-classhV base transform = classh base [transform]
+classhV base mutation = classh base [mutation]
 
 classhV' :: (Default a, CompileStyle a) => (a -> a) -> Q Exp
-classhV' transform = classh' [transform]
+classhV' mutation = classh' [mutation]
 
 
 -- | Synonym to showTW
diff --git a/src/Classh/Box.hs b/src/Classh/Box.hs
index e2fcbdd..671c945 100644
--- a/src/Classh/Box.hs
+++ b/src/Classh/Box.hs
@@ -66,6 +66,8 @@ module Classh.Box
   , border
   , position
   , shadow
+  , cursor
+  , transform
   , box_custom
   ) where
 
@@ -79,6 +81,7 @@ import Classh.Internal.TShow
 import Classh.Internal.TWNum as X
 import Classh.Responsive.WhenTW as X
 import Classh.Color as X
+import Classh.Cursor as X
 import Classh.Box.TWSize as X
 import Classh.Box.Padding as X
 import Classh.Box.Margin as X
@@ -87,9 +90,10 @@ import Classh.Box.Placement as X
 import Classh.Box.Border as X
 import Classh.Box.Shadow as X
 import Classh.Box.Transition as X
+import Classh.Box.Transform as X
 import Classh.WithTransition as X
 
-import Control.Lens hiding ((<&>))
+import Control.Lens hiding ((<&>), transform)
 import Data.Default
 import qualified Data.Text as T
 
@@ -104,6 +108,8 @@ data BoxConfig = BoxConfig
   , _border :: BorderConfig -- { rounded, thickness, etc .. }
   , _position :: WhenTW (Justify, Align)
   , _shadow :: WhenTW (WithTransition BoxShadow)  -- Transitionable!
+  , _cursor :: WhenTW CursorStyle
+  , _transform :: TransformConfig  -- All transform properties (rotate, scale, translate, skew, origin)
   , _box_custom :: T.Text
   }
   deriving Show
@@ -114,7 +120,7 @@ makeLenses ''BoxConfig
 ------------  Defaults of Records
 
 instance Default BoxConfig where
-  def = BoxConfig def def def def def def def def def def ""
+  def = BoxConfig def def def def def def def def def def def def ""
 
 
 instance CompileStyle BoxConfig where
@@ -130,6 +136,8 @@ instance CompileStyle BoxConfig where
       , compileWithTransitionTW (_bgColor cfg) ((<>) "bg-" . showTW) Transition_Colors
       , compileWithTransitionTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow) Transition_Opacity
       , compileWithTransitionTW (_shadow cfg) showTW Transition_Shadow
+      , compileWhenTW (_cursor cfg) showTW
+      , compileS (_transform cfg)
       , Right $ _box_custom cfg
       ]
       where
@@ -218,6 +226,7 @@ instance ShowTW BoxConfig where
         in prefix <> "grid" <&> prefix <> (showTW jus) <&> prefix <> (showTW align)
      ) $ _position cfg
    , renderWithTransitionTW (_shadow cfg) showTW Transition_Shadow
+   , showTW . _transform $ cfg
    , _box_custom cfg
    ]
 
@@ -236,5 +245,7 @@ instance Semigroup BoxConfig where
     , _border     = _border a   <> _border b
     , _position   = _position a <> _position b
     , _shadow     = _shadow a <> _shadow b
+    , _cursor     = _cursor a <> _cursor b
+    , _transform  = _transform a <> _transform b
     , _box_custom = _box_custom a <> _box_custom b
     }
diff --git a/src/Classh/Box/Transform.hs b/src/Classh/Box/Transform.hs
index 1e38019..ddc060c 100644
--- a/src/Classh/Box/Transform.hs
+++ b/src/Classh/Box/Transform.hs
@@ -1,3 +1,4 @@
+{-# LANGUAGE TemplateHaskell #-}
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Transform
@@ -8,20 +9,49 @@
 --  Stability   :  provisional
 --  Portability :  portable
 --
---  Types to represent tailwind scale transforms
+--  Types to represent tailwind transforms
 --  see https://v3.tailwindcss.com/docs/scale
+--  see https://v3.tailwindcss.com/docs/rotate
+--  see https://v3.tailwindcss.com/docs/translate
+--  see https://v3.tailwindcss.com/docs/skew
+--  see https://v3.tailwindcss.com/docs/transform-origin
 --
 --  Example use:
 --
 -- @
---  $(classh' [ scale .~ [("def", Scale_100), ("hover", Scale_105), ("active", Scale_95)] ])
+--  $(classh' [ transform . scale .~^ [("def", Scale_100), ("hover", Scale_105), ("active", Scale_95)] ])
+--  $(classh' [ transform . rotate .~^ [("def", Rotate_0), ("hover", Rotate_180)] ])
+--  $(classh' [ transform . translateX .~~ Translate_0 ])
 -- @
 --------------------------------------------------------------------------------
 
-module Classh.Box.Transform where
+module Classh.Box.Transform
+  ( TransformConfig(..)
+  , Scale(..)
+  , Rotate(..)
+  , Translate(..)
+  , Skew(..)
+  , TransformOrigin(..)
+  , rotate
+  , scale
+  , translateX
+  , translateY
+  , skewX
+  , skewY
+  , transformOrigin
+  ) where
 
 import Classh.Class.ShowTW
+import Classh.Class.CompileStyle
 import Classh.Internal.TShow
+import Classh.Internal.Chain
+import Classh.Responsive.WhenTW
+import Classh.WithTransition
+import Classh.Box.Transition (TransitionProperty(..))
+import Classh.Box.TWSize (TWSize, DivInt(..))
+import Classh.Internal.CSSSize (CSSSize)
+import Classh.Class.IsCSS (renderCSS)
+import Control.Lens hiding ((<&>))
 import Data.Default
 import qualified Data.Text as T
 
@@ -48,3 +78,153 @@ instance ShowTW Scale where
   showTW = \case
     Scale_Custom val -> "scale-[" <> val <> "%]"
     other -> "scale-" <> (T.drop 6 . tshow $ other)
+
+-- | Rotate transform
+-- see https://v3.tailwindcss.com/docs/rotate
+data Rotate
+  = Rotate_0      -- ^ rotate-0: transform: rotate(0deg)
+  | Rotate_1      -- ^ rotate-1: transform: rotate(1deg)
+  | Rotate_2      -- ^ rotate-2: transform: rotate(2deg)
+  | Rotate_3      -- ^ rotate-3: transform: rotate(3deg)
+  | Rotate_6      -- ^ rotate-6: transform: rotate(6deg)
+  | Rotate_12     -- ^ rotate-12: transform: rotate(12deg)
+  | Rotate_45     -- ^ rotate-45: transform: rotate(45deg)
+  | Rotate_90     -- ^ rotate-90: transform: rotate(90deg)
+  | Rotate_180    -- ^ rotate-180: transform: rotate(180deg)
+  | Rotate_Custom T.Text  -- ^ e.g., Rotate_Custom "17deg" for rotate-[17deg]
+  deriving Show
+
+instance Default Rotate where
+  def = Rotate_0
+
+instance ShowTW Rotate where
+  showTW = \case
+    Rotate_Custom val -> "rotate-[" <> val <> "]"
+    other -> "rotate-" <> (T.drop 7 . tshow $ other)
+
+-- | Translate transform (for X and Y axes)
+-- see https://v3.tailwindcss.com/docs/translate
+data Translate
+  = Translate_0
+  | Translate_Px
+  | Translate_Full
+  | Translate_TWSize TWSize         -- ^ Numeric spacing values (1, 2, 3.5, 4, etc.)
+  | Translate_Fraction Int DivInt   -- ^ Fractional values (1/2, 1/3, 2/3, 1/4, etc.)
+  | Translate_Custom CSSSize        -- ^ Custom CSS size (e.g., Rem 1.5, Percent 50)
+  deriving Show
+
+instance Default Translate where
+  def = Translate_0
+
+instance ShowTW Translate where
+  showTW = \case
+    Translate_0 -> "0"
+    Translate_Px -> "px"
+    Translate_Full -> "full"
+    Translate_TWSize sz -> showTW sz
+    Translate_Fraction num d -> tshow num <> "/" <> showTW d
+    Translate_Custom css -> "[" <> renderCSS css <> "]"
+
+-- | Skew transform (for X and Y axes)
+-- see https://v3.tailwindcss.com/docs/skew
+data Skew
+  = Skew_0   -- ^ skew-{x|y}-0: transform: skew{X|Y}(0deg)
+  | Skew_1   -- ^ skew-{x|y}-1: transform: skew{X|Y}(1deg)
+  | Skew_2   -- ^ skew-{x|y}-2: transform: skew{X|Y}(2deg)
+  | Skew_3   -- ^ skew-{x|y}-3: transform: skew{X|Y}(3deg)
+  | Skew_6   -- ^ skew-{x|y}-6: transform: skew{X|Y}(6deg)
+  | Skew_12  -- ^ skew-{x|y}-12: transform: skew{X|Y}(12deg)
+  | Skew_Custom T.Text  -- ^ e.g., Skew_Custom "17deg" for skew-x-[17deg]
+  deriving Show
+
+instance Default Skew where
+  def = Skew_0
+
+instance ShowTW Skew where
+  showTW = \case
+    Skew_Custom val -> "[" <> val <> "]"
+    other -> T.drop 5 . tshow $ other
+
+-- | Transform origin
+-- see https://v3.tailwindcss.com/docs/transform-origin
+data TransformOrigin
+  = Origin_Center        -- ^ origin-center
+  | Origin_Top           -- ^ origin-top
+  | Origin_TopRight      -- ^ origin-top-right
+  | Origin_Right         -- ^ origin-right
+  | Origin_BottomRight   -- ^ origin-bottom-right
+  | Origin_Bottom        -- ^ origin-bottom
+  | Origin_BottomLeft    -- ^ origin-bottom-left
+  | Origin_Left          -- ^ origin-left
+  | Origin_TopLeft       -- ^ origin-top-left
+  | Origin_Custom T.Text -- ^ e.g., Origin_Custom "33% 75%" for origin-[33%_75%]
+  deriving Show
+
+instance Default TransformOrigin where
+  def = Origin_Center
+
+instance ShowTW TransformOrigin where
+  showTW = \case
+    Origin_Center -> "origin-center"
+    Origin_Top -> "origin-top"
+    Origin_TopRight -> "origin-top-right"
+    Origin_Right -> "origin-right"
+    Origin_BottomRight -> "origin-bottom-right"
+    Origin_Bottom -> "origin-bottom"
+    Origin_BottomLeft -> "origin-bottom-left"
+    Origin_Left -> "origin-left"
+    Origin_TopLeft -> "origin-top-left"
+    Origin_Custom val -> "origin-[" <> val <> "]"
+
+-- | Configuration for all transform properties
+-- see https://v3.tailwindcss.com/docs/transform
+-- All transform properties can be smoothly transitioned using transition-transform
+data TransformConfig = TransformConfig
+  { _rotate :: WhenTW (WithTransition Rotate)
+  , _scale :: WhenTW (WithTransition Scale)
+  , _translateX :: WhenTW (WithTransition Translate)
+  , _translateY :: WhenTW (WithTransition Translate)
+  , _skewX :: WhenTW (WithTransition Skew)
+  , _skewY :: WhenTW (WithTransition Skew)
+  , _transformOrigin :: WhenTW TransformOrigin  -- Origin doesn't transition, just changes instantly
+  }
+  deriving Show
+
+makeLenses ''TransformConfig
+
+instance Default TransformConfig where
+  def = TransformConfig def def def def def def def
+
+instance Semigroup TransformConfig where
+  (<>) a b = TransformConfig
+    { _rotate = _rotate a <> _rotate b
+    , _scale = _scale a <> _scale b
+    , _translateX = _translateX a <> _translateX b
+    , _translateY = _translateY a <> _translateY b
+    , _skewX = _skewX a <> _skewX b
+    , _skewY = _skewY a <> _skewY b
+    , _transformOrigin = _transformOrigin a <> _transformOrigin b
+    }
+
+instance CompileStyle TransformConfig where
+  compileS cfg = do
+    pure . foldr (<&>) mempty =<< sequenceA
+      [ compileWithTransitionTW (_rotate cfg) showTW Transition_Transform
+      , compileWithTransitionTW (_scale cfg) showTW Transition_Transform
+      , compileWithTransitionTW (_translateX cfg) ((<>) "translate-x-" . showTW) Transition_Transform
+      , compileWithTransitionTW (_translateY cfg) ((<>) "translate-y-" . showTW) Transition_Transform
+      , compileWithTransitionTW (_skewX cfg) ((<>) "skew-x-" . showTW) Transition_Transform
+      , compileWithTransitionTW (_skewY cfg) ((<>) "skew-y-" . showTW) Transition_Transform
+      , compileWhenTW (_transformOrigin cfg) showTW
+      ]
+
+instance ShowTW TransformConfig where
+  showTW cfg = foldr (<&>) mempty
+    [ renderWithTransitionTW (_rotate cfg) showTW Transition_Transform
+    , renderWithTransitionTW (_scale cfg) showTW Transition_Transform
+    , renderWithTransitionTW (_translateX cfg) ((<>) "translate-x-" . showTW) Transition_Transform
+    , renderWithTransitionTW (_translateY cfg) ((<>) "translate-y-" . showTW) Transition_Transform
+    , renderWithTransitionTW (_skewX cfg) ((<>) "skew-x-" . showTW) Transition_Transform
+    , renderWithTransitionTW (_skewY cfg) ((<>) "skew-y-" . showTW) Transition_Transform
+    , renderWhenTW (_transformOrigin cfg) showTW
+    ]
diff --git a/test/TransformTest.hs b/test/TransformTest.hs
new file mode 100644
index 0000000..4f9b640
--- /dev/null
+++ b/test/TransformTest.hs
@@ -0,0 +1,186 @@
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module Main where
+
+import Classh
+import Classh.Class.CompileStyle
+import Control.Lens ((&))
+import Data.Default (def)
+import qualified Data.Text as T
+
+-- Test 1: Basic rotation
+test1 :: BoxConfig
+test1 = def
+  & transform . rotate .~^ [("def", noTransition Rotate_0), ("hover", noTransition Rotate_180)]
+
+-- Test 2: Scale with transition
+test2 :: BoxConfig
+test2 = def
+  & transform . scale .~^ [ ("def", noTransition Scale_100)
+                          , ("hover", Scale_105 `withTransition` Duration_300)
+                          ]
+
+-- Test 3: Translate X with TWSize
+test3 :: BoxConfig
+test3 = def
+  & transform . translateX .~^ [("def", noTransition (Translate_TWSize (TWSize 4)))]
+
+-- Test 4: Translate Y with fraction
+test4 :: BoxConfig
+test4 = def
+  & transform . translateY .~^ [("def", noTransition (Translate_Fraction 1 D2))]
+
+-- Test 5: Translate with custom CSS size
+test5 :: BoxConfig
+test5 = def
+  & transform . translateX .~^ [("def", noTransition (Translate_Custom (Rem 1.5)))]
+
+-- Test 6: Skew transform
+test6 :: BoxConfig
+test6 = def
+  & transform . skewX .~^ [("def", noTransition Skew_0), ("hover", noTransition Skew_6)]
+
+-- Test 7: Transform origin
+test7 :: BoxConfig
+test7 = def
+  & transform . transformOrigin .~~ Origin_TopRight
+
+-- Test 8: Combined transforms with transitions
+test8 :: BoxConfig
+test8 = def
+  & transform . rotate .~^ [ ("def", noTransition Rotate_0)
+                           , ("hover", Rotate_45 `withTransition` Duration_300)
+                           ]
+  & transform . scale .~^ [ ("def", noTransition Scale_100)
+                          , ("hover", Scale_110 `withTransition` Duration_300)
+                          ]
+
+-- Test 9: All rotation values
+test9 :: BoxConfig
+test9 = def
+  & transform . rotate .~^ [("def", noTransition Rotate_90)]
+
+-- Test 10: All scale values
+test10 :: BoxConfig
+test10 = def
+  & transform . scale .~^ [("def", noTransition Scale_95)]
+
+-- Test 11: Translate with 0
+test11 :: BoxConfig
+test11 = def
+  & transform . translateX .~^ [("def", noTransition Translate_0)]
+
+-- Test 12: Translate with px
+test12 :: BoxConfig
+test12 = def
+  & transform . translateY .~^ [("def", noTransition Translate_Px)]
+
+-- Test 13: Translate with full
+test13 :: BoxConfig
+test13 = def
+  & transform . translateX .~^ [("def", noTransition Translate_Full)]
+
+-- Test 14: Custom rotate
+test14 :: BoxConfig
+test14 = def
+  & transform . rotate .~^ [("def", noTransition (Rotate_Custom "17deg"))]
+
+-- Test 15: Custom scale
+test15 :: BoxConfig
+test15 = def
+  & transform . scale .~^ [("def", noTransition (Scale_Custom "102"))]
+
+testCase :: String -> BoxConfig -> T.Text -> IO Bool
+testCase name cfg expected = do
+  putStrLn $ "\n" ++ replicate 80 '-'
+  putStrLn $ "TEST: " ++ name
+  putStrLn $ replicate 80 '-'
+  case compileS cfg of
+    Left err -> do
+      putStrLn $ "❌ ERROR: " ++ show err
+      return False
+    Right result -> do
+      let success = result == expected
+      putStrLn $ "Output:"
+      putStrLn $ "  " ++ show result
+      putStrLn ""
+      if success
+        then putStrLn "✓ PASS"
+        else do
+          putStrLn "✗ FAIL"
+          putStrLn $ "\nExpected:"
+          putStrLn $ "  " ++ show expected
+      return success
+
+main :: IO ()
+main = do
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                       Transform Feature Test Suite"
+  putStrLn $ replicate 80 '='
+
+  results <- sequenceA
+    [ testCase "Test 1 (basic rotation)"
+        test1
+        "rotate-0 hover:rotate-180"
+    , testCase "Test 2 (scale with transition)"
+        test2
+        "scale-100 hover:scale-105 hover:[transition:transform_300ms_linear_0ms]"
+    , testCase "Test 3 (translate X with TWSize)"
+        test3
+        "translate-x-4"
+    , testCase "Test 4 (translate Y with fraction)"
+        test4
+        "translate-y-1/2"
+    , testCase "Test 5 (translate X with custom CSS size)"
+        test5
+        "translate-x-[1.5rem]"
+    , testCase "Test 6 (skew transform)"
+        test6
+        "skew-x-0 hover:skew-x-6"
+    , testCase "Test 7 (transform origin)"
+        test7
+        "origin-top-right"
+    , testCase "Test 8 (combined transforms with transitions)"
+        test8
+        "rotate-0 hover:rotate-45 hover:[transition:transform_300ms_linear_0ms] scale-100 hover:scale-110 hover:[transition:transform_300ms_linear_0ms]"
+    , testCase "Test 9 (rotate 90)"
+        test9
+        "rotate-90"
+    , testCase "Test 10 (scale 95)"
+        test10
+        "scale-95"
+    , testCase "Test 11 (translate X 0)"
+        test11
+        "translate-x-0"
+    , testCase "Test 12 (translate Y px)"
+        test12
+        "translate-y-px"
+    , testCase "Test 13 (translate X full)"
+        test13
+        "translate-x-full"
+    , testCase "Test 14 (custom rotate)"
+        test14
+        "rotate-[17deg]"
+    , testCase "Test 15 (custom scale)"
+        test15
+        "scale-[102%]"
+    ]
+
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                              SUMMARY"
+  putStrLn $ replicate 80 '='
+  let passed = length $ filter id results
+      total = length results
+  putStrLn $ "Tests passed: " ++ show passed ++ "/" ++ show total
+  putStrLn ""
+
+  if and results
+    then do
+      putStrLn "✓ ALL TESTS PASSED!"
+      putStrLn $ replicate 80 '='
+    else do
+      putStrLn "✗ SOME TESTS FAILED"
+      putStrLn $ replicate 80 '='
diff --git a/test/TransitionTest.hs b/test/TransitionTest.hs
index 328ec9c..5fa9aa3 100644
--- a/test/TransitionTest.hs
+++ b/test/TransitionTest.hs
@@ -4,14 +4,7 @@
 module Main where
 
 import Classh
-import Classh.Box
-import Classh.Box.Padding
-import Classh.Color
-import Classh.Box.Transition
-import Classh.WithTransition
-import Classh.Setters
 import Classh.Class.CompileStyle
-import Classh.Class.SetSides
 import Control.Lens ((&))
 import Data.Default (def)
 import qualified Data.Text as T

From 38fd54179ec7ec682c63fc4825f21acaa17666f2 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Fri, 20 Feb 2026 14:36:38 -0500
Subject: [PATCH 18/29] turn off -Wall for now

---
 ClasshSS.cabal | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ClasshSS.cabal b/ClasshSS.cabal
index 1b872c2..b00be03 100644
--- a/ClasshSS.cabal
+++ b/ClasshSS.cabal
@@ -26,7 +26,7 @@ extra-doc-files:    CHANGELOG.md
 -- extra-source-files:
 
 common warnings
-    ghc-options: -Wall -Werror
+    ghc-options: -Wall 
 
 library
     import:           warnings

From 9cdff2836451f8ee7cd131f0439381a83a1aa14a Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Sun, 22 Feb 2026 18:29:32 -0500
Subject: [PATCH 19/29] docs: improve README and add documentation guides

- Rewrite README for clarity
- Add EXAMPLE.md with usage patterns
- Add MIGRATION_FROM_TAILWIND.md guide
---
 README.md                       | 220 +++++----------
 docs/EXAMPLE.md                 | 245 +++++++++++++++++
 docs/MIGRATION_FROM_TAILWIND.md | 461 ++++++++++++++++++++++++++++++++
 3 files changed, 774 insertions(+), 152 deletions(-)
 create mode 100644 docs/EXAMPLE.md
 create mode 100644 docs/MIGRATION_FROM_TAILWIND.md

diff --git a/README.md b/README.md
index f7fcc51..52a89b3 100644
--- a/README.md
+++ b/README.md
@@ -1,194 +1,110 @@
 # ClasshSS
 
-Type-safe CSS-in-Haskell based on Tailwind CSS.
+Type-safe CSS-in-Haskell built on Tailwind CSS. Generates class strings with compile-time validation.
 
 ## Overview
 
-ClasshSS lets you write Tailwind-style CSS in Haskell with compile-time checking. It prevents common mistakes like conflicting class definitions and ensures your styles are valid before runtime.
+ClasshSS is a library that generates Tailwind CSS class strings in Haskell with compile-time type safety. It provides two main configuration types:
 
-Two main config types:
-- `BoxConfig` - element styling (layout, colors, borders, shadows)
-- `TextConfigTW` - text styling (font, size, weight, color)
+- `BoxConfig` - Element styling (layout, colors, borders, shadows, spacing)
+- `TextConfigTW` - Text styling (font, size, weight, color)
 
-## Basic Example
+The library generates `Text` values containing Tailwind classes. These work with any DOM library (Reflex.Dom, Lucid, Blaze, IHP, etc.).
 
-```haskell
-import Classh
-import Reflex.Dom.Core
-
--- Box with styled text
-elClass "div" $(classh' [ pt .~~ TWSize 20, bgColor .~~ Gray C300 ]) $ do
-  textS $(classh' [text_size .|~ [XL, XL2]]) "Hello"
-```
-
-## Operators
-
-**`.~~`** - Set value for all screen sizes
-```haskell
-bgColor .~~ hex "281C40"
-br .~~ R_3Xl
-shadow .~~ Shadow_Md
-```
-
-**`.|~`** - Responsive values `[mobile, sm, md, lg, xl, 2xl]`
-```haskell
-w .|~ [TWSize 12, TWSize 24, TWSize 48]
-text_size .|~ [Base, LG, XL, XL2]
-```
-
-**`.~^`** - Stateful values (hover, focus, etc.) with transitions
-```haskell
-bgColor .~^ [("def", noTransition $ hex "281C40")
-           , ("hover", hex "7B4DF4" `withTransition` Duration_300)
-           ]
-```
-
-**`.~`** - Simple setter (mainly for `custom`)
-```haskell
-custom .~ "flex items-center"
-```
-
-## Common Properties
-
-### Box (BoxConfig)
-
-```haskell
--- Spacing
-pt, pb, pl, pr, px, py, p      -- padding
-mt, mb, ml, mr, mx, my, m      -- margin
-
--- Sizing
-w, h                            -- width, height
-minW, maxW, minH, maxH         -- constraints
-
--- Border
-br, bw, bc                     -- radius, width, color
-br_t, br_b, br_l, br_r         -- individual corners
-
--- Colors
-bgColor                        -- background
-bc                             -- border color
+## Installation
 
--- Layout
-pos                            -- position (justify, align)
-colStart, colSpan              -- grid columns
-
--- Visual
-shadow                         -- box shadow
+Add to your `.cabal` file:
+```cabal
+build-depends:
+    classhss
 ```
 
-### Text (TextConfigTW)
-
-```haskell
-text_size                      -- XS, SM, Base, LG, XL, XL2, XL3, etc.
-text_color                     -- any Color
-text_weight                    -- Light, Normal, Medium, Semibold, Bold, etc.
-text_font                      -- Font_Sans, Font_Serif, Font_Custom "Name"
-text_align                     -- Left, Center, Right, Justify
-```
-
-## Shorthand
-
-Instead of `border . radius . allS`, use `br`:
-```haskell
-$(classh' [ br .~~ R_3Xl
-          , bw .~~ B2
-          , bc .~~ hex "7B4DF4"
-          ])
+Or with Stack, add to `stack.yaml`:
+```yaml
+extra-deps:
+  - classhss-0.1.0.0
 ```
 
-## Colors
+## Quick Start
 
 ```haskell
--- Hex colors
-hex "281C40"
+{-# LANGUAGE TemplateHaskell #-}
 
--- Tailwind colors
-Gray C300
-Red C500
-Blue C600
+import Classh
+import Reflex.Dom.Core
 
--- Standard
-White
-Black
+-- Simple styled div
+myDiv :: DomBuilder t m => m ()
+myDiv = elClass "div" $(classh'
+  [ bgColor .~~ Blue C500
+  , p .~~ TWSize 4
+  , br .~~ R_Md
+  ]) $ text "Hello, ClasshSS!"
 ```
 
-## Transitions
+### Four Operators
 
-```haskell
--- Basic
-bgColor .~^ [("def", noTransition purple)
-           , ("hover", lavender `withTransition` Duration_300)
-           ]
-
--- With timing
-shadow .~^ [("def", noTransition Shadow_Md)
-          , ("hover", Shadow_Lg `withTransition` Duration_300
-                                `withTiming` Ease_InOut)
-          ]
-
--- All at once
-bgColor .~^ [("def", noTransition blue)
-           , ("hover", purple `withTransitionAll` Duration_300 Ease_In Delay_0)
-           ]
-```
+- `.~~` - Constant value (no responsive, no states)
+- `.|~` - Responsive values (mobile-first breakpoints)
+- `.~^` - State-based values (hover, focus, active) with transitions
+- `.~` - Direct setter (mainly for `custom` field)
 
-## Template Haskell
+## Complete Example
 
-**`classh'`** - Compile with defaults
-```haskell
-$(classh' [ bgColor .~~ hex "281C40" ])
-```
+See **[docs/EXAMPLE.md](docs/EXAMPLE.md)** for a comprehensive example showing:
+- BoxConfig applied to elements via `classh'`
+- TextConfigTW for text styling (via `textS` from reflex-classh)
+- TextPosition for text positioning (via `textPosition` from reflex-classh)
+- Responsive design with `.|~`
+- State-based transitions with `.~^`
+- Grid positioning
+- Transform composition
 
-**`classh`** - Compile with custom base config
-```haskell
-$(classh myBaseConfig [ text_size .~~ XL2 ])
-```
-
-**`classhUnsafe`** - Runtime (no TH, for library functions)
-```haskell
-classhUnsafe [ bgColor .~~ hex "281C40" ]
-```
+## Migrating from Tailwind
 
-The TH versions check for conflicts at compile-time. For example, setting both `pt` and `py` will fail to compile since they overlap.
+If you're familiar with Tailwind CSS, see **[docs/MIGRATION_FROM_TAILWIND.md](docs/MIGRATION_FROM_TAILWIND.md)** for:
+- Class name mappings (e.g., `bg-blue-500` → `bgColor .~~ Blue C500`)
+- How to translate responsive patterns
+- How to translate hover/focus states
+- Common migration patterns
 
-## Usage with Reflex
+## API Documentation
 
-```haskell
--- Static classes
-elClass "div" $(classh' [ w .~~ TWSize_Full, p .~~ TWSize 4 ]) $
-  text "content"
-
--- Dynamic classes
-dynClasses <- holdDyn (classhUnsafe [bgColor .~~ Gray C300]) $ ...
-elDynClass "div" dynClasses $ text "content"
-
--- Text with styling
-textS $(classh' [ text_size .~~ XL3
-                , text_color .~~ hex "F3F1F8"
-                , text_weight .~~ Bold
-                ]) "Hello"
-```
+For complete API reference:
+- Run `cabal haddock` to generate documentation
+- See Haddock comments in source files (especially `src/Classh.hs`)
+- The main module Haddock includes the comprehensive example
 
 ## Why ClasshSS?
 
 - **Type safety** - Invalid CSS won't compile
 - **No conflicts** - Can't accidentally set overlapping properties
-- **Responsive by default** - Easy to write mobile-first styles
+- **Responsive by default** - Easy mobile-first design
 - **Transitions built-in** - Type-safe hover/focus states
 - **Tailwind familiar** - If you know Tailwind, you know ClasshSS
-- **Explicit layout** - Strict about width/height consumption, no flexbox magic
 
-## Layout Philosophy
+## Important Notes
+
+### Type Separation
 
-ClasshSS intentionally does NOT support `display: flex` or flexbox properties. The design philosophy is to be incredibly strict about layout and make it easy to see how each element "consumes" width or height from the page in a responsive, declarative manner.
+You cannot mix `BoxConfig` and `TextConfigTW` in the same `classh'` call. This is enforced by the type system:
 
-For layouts requiring flex, use the `custom` field:
 ```haskell
-custom .~ "flex flex-col items-center"
+-- ERROR: Won't compile!
+$(classh' [ bgColor .~~ Blue C500, text_color .~~ White ])
+
+-- CORRECT: Separate configs, nested elements
+elClass "div" $(classh' [bgColor .~~ Blue C500]) $
+  textS $(classhText [text_color .~~ White]) "Text"
 ```
 
-This keeps layout behavior explicit and separate from the type-safe styling that ClasshSS provides.
+### Avoid Flexbox
+
+ClasshSS recommends using CSS Grid instead of flexbox due to flexbox's non-deterministic sizing behavior. Use the `custom` field only as a last resort.
+
+### The `custom` Field
+
+The `custom` field bypasses type safety and can override type-safe properties. Only use it when absolutely necessary, and place it **first** in your config list so type-safe properties take precedence.
 
 ## License
 
diff --git a/docs/EXAMPLE.md b/docs/EXAMPLE.md
new file mode 100644
index 0000000..ff358bf
--- /dev/null
+++ b/docs/EXAMPLE.md
@@ -0,0 +1,245 @@
+# ClasshSS Comprehensive Example
+
+This is **the** example showing all ClasshSS concepts in one place.
+
+## Complete Working Example
+
+```haskell
+{-# LANGUAGE TemplateHaskell #-}
+
+module Example where
+
+import Classh
+import Reflex.Dom.Core
+import Reflex.Classh (textS, textPosition)  -- Note: from reflex-classh package
+
+-- Complete example: styled card with positioned text
+exampleCard :: (DomBuilder t m, PostBuild t m) => m ()
+exampleCard =
+  -- BoxConfig: All element-level styling
+  elClass "div" $(classh'
+    [ -- Colors
+      bgColor .~~ White
+    , border . bColor . all .~~ Gray C200
+
+    , -- Spacing
+      p .~~ TWSize 6
+    , m .~~ TWSize 4
+
+    , -- Shape
+      br .~~ R_Lg
+    , border . bWidth . all .~~ B1
+
+    , -- Shadow & hover effect
+      shadow .~^ [ ("def", noTransition Shadow_Sm)
+                 , ("hover", Shadow_Lg `withTransition` Duration_300)
+                 ]
+
+    , -- Transform on hover
+      transform . scale .~^ [ ("def", noTransition Scale_100)
+                            , ("hover", Scale_105 `withTransition` Duration_200)
+                            ]
+
+    , -- Grid positioning (NOT flex - avoid flexbox)
+      colStart .~~ 2
+    , colSpan .~~ 4
+
+    , -- Cursor
+      cursor .~~ CursorPointer
+    ]) $ do
+      -- TextConfigTW: Text styling via textS (from reflex-classh)
+      textS $(classhText
+        [ text_color .~~ Gray C900
+        , text_size .~~ TextXl
+        , text_weight .~~ FontBold
+        ]) "Card Title"
+
+      -- TextPosition: Position text (from reflex-classh)
+      el "p" $ textPosition $(classhTextPos
+        [ textAlign .~~ TextCenter
+        , textTransform .~~ Uppercase
+        ]) $ text "Centered uppercase text"
+
+      -- More content with separate styling
+      textS $(classhText
+        [ text_color .~~ Gray C600
+        , text_size .~~ TextSm
+        ]) "Card description text"
+```
+
+## What This Example Shows
+
+### 1. BoxConfig (Element-Level Styling)
+
+Applied to the `<div>` via `classh'`:
+
+- **Colors**: `bgColor`, `border . bColor`
+- **Spacing**: `p` (padding), `m` (margin)
+- **Shape**: `br` (border radius), `border . bWidth`
+- **Shadows**: With state transitions using `.~^`
+- **Transforms**: Scale on hover with transitions
+- **Grid**: `colStart`, `colSpan` for grid positioning
+- **Cursor**: Mouse cursor style
+
+### 2. TextConfigTW (Text-Level Styling)
+
+Applied via `textS` from **reflex-classh** package:
+
+- **Color**: `text_color`
+- **Size**: `text_size`
+- **Weight**: `text_weight`
+
+**Critical:** Cannot mix BoxConfig and TextConfigTW in the same `classh'` call!
+
+### 3. TextPosition (Text Positioning)
+
+Applied via `textPosition` from **reflex-classh** package:
+
+- **Alignment**: `textAlign`
+- **Transform**: `textTransform` (uppercase, lowercase, etc.)
+
+### 4. The Four Operators
+
+```haskell
+.~~   -- Constant value (no responsive, no states)
+.|~   -- Responsive values (mobile-first breakpoints)
+.~^   -- State-based values (hover, focus, active)
+.~    -- Direct setter (rarely used)
+```
+
+### 5. Type Separation
+
+**This will NOT compile:**
+```haskell
+-- ERROR: Mixing BoxConfig and TextConfigTW!
+$(classh'
+  [ bgColor .~~ Blue C500      -- BoxConfig
+  , text_color .~~ White       -- TextConfigTW - ERROR!
+  ])
+```
+
+**Correct:**
+```haskell
+-- Separate configs, nested elements
+elClass "div" $(classh' [bgColor .~~ Blue C500]) $
+  textS $(classhText [text_color .~~ White]) "Text"
+```
+
+### 6. Responsive Design
+
+```haskell
+p .|~ [ ("mobile", TWSize 4)   -- 0px+
+      , ("md", TWSize 6)        -- 768px+
+      , ("lg", TWSize 8)        -- 1024px+
+      ]
+```
+
+### 7. Transitions
+
+```haskell
+shadow .~^ [ ("def", noTransition Shadow_Sm)
+           , ("hover", Shadow_Lg `withTransition` Duration_300)
+           ]
+```
+
+### 8. Grid (Not Flexbox!)
+
+ClasshSS supports grid positioning but **avoid flexbox** due to non-deterministic behavior:
+
+```haskell
+-- GOOD: Grid
+colStart .~~ ColStart_2
+colSpan .~~ ColSpan_4
+
+-- BAD: Flexbox (non-deterministic)
+custom .~ "flex justify-center"  -- AVOID!
+```
+
+## Common Patterns
+
+### Simple Button
+
+```haskell
+simpleButton :: (DomBuilder t m, PostBuild t m) => Text -> m ()
+simpleButton label =
+  elClass "button" $(classh'
+    [ bgColor .~~ Blue C500
+    , px .~~ TWSize 6
+    , py .~~ TWSize 3
+    , br .~~ R_Md
+    ]) $
+      textS $(classhText [text_color .~~ White]) label
+```
+
+### Hover Effect
+
+```haskell
+hoverable :: Text
+hoverable = $(classh'
+  [ bgColor .~^ [ ("def", noTransition (Blue C500))
+                , ("hover", Blue C600 `withTransition` Duration_200)
+                ]
+  ])
+```
+
+### Responsive Spacing
+
+```haskell
+responsivePadding :: Text
+responsivePadding = $(classh'
+  [ p .|~ [ ("mobile", TWSize 4)
+          , ("md", TWSize 6)
+          , ("lg", TWSize 8)
+          ]
+  ])
+```
+
+## Important Notes
+
+### Functions from reflex-classh
+
+These functions are in the separate **reflex-classh** package:
+- `textS` - Apply TextConfigTW to text
+- `textPosition` - Apply TextPosition to text
+
+### Functions from ClasshSS
+
+These are from the main **ClasshSS** package:
+- `classh'` - Generate class string from config
+- `classhText` - Same as `classh'`, semantic alias for TextConfigTW
+- `classhTextPos` - Generate class string from TextPosition
+
+### Avoid `custom` Field
+
+The `custom` field bypasses type safety. Only use as last resort:
+
+```haskell
+-- DANGEROUS: custom can override type-safe properties!
+$(classh'
+  [ bgColor .~~ White
+  , custom .~ "bg-blue-500"  -- Overrides bgColor! No compile error!
+  ])
+
+-- If you must use custom, place it FIRST:
+$(classh'
+  [ custom .~ "grid grid-cols-3"  -- No type-safe alternative
+  , bgColor .~~ White             -- Type-safe, takes precedence
+  ])
+```
+
+### Avoid Flexbox
+
+Flexbox has non-deterministic sizing behavior. Use CSS Grid instead:
+
+```haskell
+-- AVOID
+custom .~ "flex items-center justify-between"
+
+-- PREFER
+custom .~ "grid place-items-center"
+```
+
+## See Also
+
+- **API Documentation**: Run `cabal haddock` or see Haddock in source files
+- **Migration Guide**: [MIGRATION_FROM_TAILWIND.md](MIGRATION_FROM_TAILWIND.md)
diff --git a/docs/MIGRATION_FROM_TAILWIND.md b/docs/MIGRATION_FROM_TAILWIND.md
new file mode 100644
index 0000000..5b4b4cf
--- /dev/null
+++ b/docs/MIGRATION_FROM_TAILWIND.md
@@ -0,0 +1,461 @@
+# Migrating from Tailwind CSS to ClasshSS
+
+If you're already familiar with Tailwind CSS, this guide will help you quickly translate your knowledge to ClasshSS.
+
+## Core Philosophy
+
+ClasshSS follows Tailwind's utility-first approach but adds:
+- **Type safety** - Invalid CSS won't compile
+- **No runtime errors** - Catch mistakes at compile-time
+- **Functional composition** - Leverage Haskell's strengths
+- **Template Haskell** - Generate optimized class strings
+
+## Quick Comparison
+
+### HTML/JSX (Tailwind)
+```html
+<div class="bg-blue-500 p-8 rounded-lg hover:bg-blue-700">
+  <h1 class="text-2xl font-bold text-white">Hello</h1>
+</div>
+```
+
+### Haskell (ClasshSS)
+```haskell
+elClass "div" $(classh'
+  [ bgColor .~^ [("def", noTransition (Blue C500)), ("hover", Blue C700 `withTransition` Duration_300)]
+  , p .~~ TWSize 8
+  , br .~~ R_Lg
+  ]) $ do
+    textS $(classh' [text_size .~~ XL2, text_weight .~~ Bold, text_color .~~ White]) "Hello"
+```
+
+## Class Name Mapping
+
+### Colors
+
+| Tailwind | ClasshSS |
+|----------|----------|
+| `bg-blue-500` | `bgColor .~~ Blue C500` |
+| `bg-gray-300` | `bgColor .~~ Gray C300` |
+| `bg-red-600` | `bgColor .~~ Red C600` |
+| `bg-[#281C40]` | `bgColor .~~ hex "281C40"` |
+| `text-blue-500` | `text_color .~~ Blue C500` |
+| `border-gray-300` | `bc .~~ Gray C300` (shorthand for border color all sides) |
+
+**Pattern:** `ColorFamily CShade`
+
+Available shades: C50, C100, C200, C300, C400, C500, C600, C700, C800, C900, C950
+
+### Spacing (Padding & Margin)
+
+| Tailwind | ClasshSS |
+|----------|----------|
+| `p-4` | `p .~~ TWSize 4` |
+| `pt-4` | `pt .~~ TWSize 4` |
+| `pb-4` | `pb .~~ TWSize 4` |
+| `px-4` | `px .~~ TWSize 4` |
+| `py-4` | `py .~~ TWSize 4` |
+| `pl-8` | `pl .~~ TWSize 8` |
+| `pr-8` | `pr .~~ TWSize 8` |
+| `m-4` | `m .~~ TWSize 4` |
+| `mt-4`, `mb-4`, `ml-4`, `mr-4` | `mt/mb/ml/mr .~~ TWSize 4` |
+| `mx-auto` | `mx .~~ TWSize_Auto` |
+| `p-[20px]` | `p .~~ pix 20` (custom pixel value) |
+
+**Pattern:** Same abbreviations, but use `.~~` operator and `TWSize` constructor
+
+### Sizing
+
+| Tailwind | ClasshSS |
+|----------|----------|
+| `w-64` | `w .~~ TWSize' (TWSize 64)` |
+| `w-full` | `w .~~ TWSize_Full` |
+| `w-screen` | `w .~~ TWSize_Screen` |
+| `w-auto` | `w .~~ TWSize_Auto` |
+| `w-1/2` | `w .~~ TWFraction 1 D2` |
+| `w-11/12` | `w .~~ TWFraction 11 D12` |
+| `w-[400px]` | `w .~~ TWSize_Custom (pix 400)` |
+| `h-64` | `h .~~ TWSize' (TWSize 64)` |
+| `max-w-screen` | `maxW .~~ TWSize_Screen` |
+| `min-h-screen` | `minH .~~ TWSize_Screen` |
+
+### Borders
+
+| Tailwind | ClasshSS |
+|----------|----------|
+| `rounded-md` | `br .~~ R_Md` |
+| `rounded-lg` | `br .~~ R_Lg` |
+| `rounded-full` | `br .~~ R_Full` |
+| `rounded-none` | `br .~~ R_None` |
+| `rounded-t-lg` | `br_t .~~ R_Lg` (top corners) |
+| `border-2` | `bw .~~ B2` (all sides) |
+| `border-t-2` | `bw_t .~~ B2` (top only) |
+| `border-gray-300` | `bc .~~ Gray C300` (all sides) |
+| `border-solid` | `border . bStyle .~~ Solid` |
+
+**Shortcuts:**
+- `br` = border radius (all corners)
+- `br_t`, `br_b`, `br_l`, `br_r` = individual sides
+- `bw` = border width
+- `bc` = border color
+
+### Shadows
+
+| Tailwind | ClasshSS |
+|----------|----------|
+| `shadow-sm` | `shadow .~~ Shadow_Sm` |
+| `shadow` | `shadow .~~ Shadow` |
+| `shadow-md` | `shadow .~~ Shadow_Md` |
+| `shadow-lg` | `shadow .~~ Shadow_Lg` |
+| `shadow-xl` | `shadow .~~ Shadow_Xl` |
+| `shadow-2xl` | `shadow .~~ Shadow_2Xl` |
+| `shadow-none` | `shadow .~~ Shadow_None` |
+
+### Text Styling
+
+| Tailwind | ClasshSS |
+|----------|----------|
+| `text-xs` | `text_size .~~ XS` |
+| `text-sm` | `text_size .~~ SM` |
+| `text-base` | `text_size .~~ Base` |
+| `text-lg` | `text_size .~~ LG` |
+| `text-xl` | `text_size .~~ XL` |
+| `text-2xl` | `text_size .~~ XL2` |
+| `text-3xl` | `text_size .~~ XL3` |
+| `font-bold` | `text_weight .~~ Bold` |
+| `font-semibold` | `text_weight .~~ Semibold` |
+| `font-normal` | `text_weight .~~ Normal` |
+| `italic` | `text_style .~~ Italic` |
+| `text-center` | Use `text_align` in TextPosition |
+
+### Transforms
+
+| Tailwind | ClasshSS |
+|----------|----------|
+| `rotate-45` | `transform . rotate .~~ Rotate_45` |
+| `rotate-90` | `transform . rotate .~~ Rotate_90` |
+| `scale-100` | `transform . scale .~~ Scale_100` |
+| `scale-105` | `transform . scale .~~ Scale_105` |
+| `translate-x-4` | `transform . translateX .~~ Translate_TWSize (TWSize 4)` |
+| `skew-x-3` | `transform . skewX .~~ Skew_3` |
+
+## Responsive Design
+
+### Tailwind
+```html
+<div class="text-sm md:text-base lg:text-lg xl:text-xl">
+  Responsive text
+</div>
+```
+
+### ClasshSS
+```haskell
+$(classh' [ text_size .|~ [SM, Base, LG, XL] ])
+```
+
+**Breakpoint mapping:**
+```haskell
+-- Tailwind            ClasshSS
+-- (default)           [0] = mobile/base
+-- sm:                 [1] = sm
+-- md:                 [2] = md
+-- lg:                 [3] = lg
+-- xl:                 [4] = xl
+-- 2xl:                [5] = 2xl
+
+-- Example: different background at each breakpoint
+bgColor .|~ [Gray C100, Gray C200, Gray C300, Gray C400, Gray C500, Gray C600]
+--        mobile    sm         md         lg         xl         2xl
+```
+
+**Tips:**
+- List order: `[mobile, sm, md, lg, xl, 2xl]`
+- You don't need to provide all 6 values - fewer values work too
+- Mobile-first: earlier values apply until overridden
+
+## Hover & Focus States
+
+### Tailwind
+```html
+<button class="bg-blue-500 hover:bg-blue-700 focus:ring-2">
+  Click me
+</button>
+```
+
+### ClasshSS
+```haskell
+$(classh'
+  [ bgColor .~^ [ ("def", noTransition (Blue C500))
+                , ("hover", Blue C700 `withTransition` Duration_300)
+                ]
+  , border . ring . ringWidth .~^ [ ("def", noTransition Ring_0)
+                                  , ("focus", Ring_2 `withTransition` Duration_200)
+                                  ]
+  ])
+```
+
+**Available states:**
+- `"def"` - Default/base state
+- `"hover"` - Mouse hover
+- `"focus"` - Keyboard/click focus
+- `"active"` - Active state
+
+**Important differences:**
+- ClasshSS requires explicit `noTransition` for default state
+- Transitions are built into the syntax with `withTransition`
+- Can combine states with screen sizes (advanced)
+
+## Transitions
+
+### Tailwind
+```html
+<div class="transition duration-300 ease-in-out hover:scale-105">
+  Hover me
+</div>
+```
+
+### ClasshSS
+```haskell
+$(classh'
+  [ transform . scale .~^ [ ("def", noTransition Scale_100)
+                          , ("hover", Scale_105 `withTransition` Duration_300 `withTiming` Ease_InOut)
+                          ]
+  ])
+```
+
+**Transition durations:**
+- `Duration_75`, `Duration_100`, `Duration_150`, `Duration_200`, `Duration_300`, `Duration_500`, `Duration_700`, `Duration_1000`
+
+**Timing functions:**
+- `Ease_Linear` (linear)
+- `Ease_In` (ease-in)
+- `Ease_Out` (ease-out)
+- `Ease_InOut` (ease-in-out)
+
+**Builder pattern:**
+```haskell
+value `withTransition` Duration_300                    -- Just duration
+value `withTransition` Duration_300 `withTiming` Ease_In    -- Duration + timing
+value `withTransition` Duration_300 `withDelay` Delay_100   -- Duration + delay
+
+-- All at once:
+value `withTransitionAll` Duration_300 Ease_InOut Delay_0
+```
+
+## Flexbox & Grid
+
+### WARNING: Avoid Flexbox Due to Non-Determinism
+
+**ClasshSS intentionally does not support flexbox** - and we **strongly recommend avoiding flexbox entirely** due to its non-deterministic behavior.
+
+**Why avoid flexbox:**
+- **Non-deterministic sizing** - Flex items can have unpredictable sizes depending on content
+- **Layout instability** - Changes in one item can affect the entire flex container
+- **Hard to reason about** - Complex interaction between flex properties makes debugging difficult
+- **Browser inconsistencies** - Different browsers may render flex layouts differently
+
+### Tailwind (with flexbox - NOT recommended)
+```html
+<div class="flex flex-col items-center gap-4">
+  Content
+</div>
+```
+
+### ClasshSS - Do NOT use flexbox
+```haskell
+-- DO NOT DO THIS - Non-deterministic!
+$(classh'
+  [ custom .~ "flex flex-col items-center gap-4"  -- AVOID!
+  , bgColor .~~ Gray C50
+  , p .~~ TWSize 4
+  ])
+```
+
+**Recommended alternatives:**
+- Use **CSS Grid** for 2D layouts (deterministic, explicit positioning)
+- Use **fixed positioning** with padding/margin for simple layouts
+- Use **absolute positioning** when appropriate
+
+If you absolutely must use flexbox (not recommended), use the `custom` field, but understand the risks.
+
+### Grid Layout (Supported)
+
+ClasshSS supports grid positioning:
+
+```haskell
+$(classh'
+  [ colStart .~~ 1        -- grid-column-start
+  , colSpan .~~ 6         -- grid-column-span
+  ])
+```
+
+## Common Patterns
+
+### Card Component
+
+**Tailwind:**
+```html
+<div class="bg-white rounded-lg shadow-lg p-6 border border-gray-200">
+  Card content
+</div>
+```
+
+**ClasshSS:**
+```haskell
+$(classh'
+  [ bgColor .~~ White
+  , br .~~ R_Lg
+  , shadow .~~ Shadow_Lg
+  , p .~~ TWSize 6
+  , border . bWidth . allS .~~ B1
+  , border . bColor . allS .~~ Gray C200
+  ])
+```
+
+### Button with Hover
+
+**Tailwind:**
+```html
+<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
+  Button
+</button>
+```
+
+**ClasshSS:**
+```haskell
+buttonClasses = $(classh'
+  [ bgColor .~^ [("def", noTransition (Blue C500)), ("hover", Blue C700 `withTransition` Duration_200)]
+  , py .~~ TWSize 2
+  , px .~~ TWSize 4
+  , br .~~ R_Normal
+  ])
+
+buttonText = $(classh' [text_color .~~ White, text_weight .~~ Bold])
+```
+
+### Container
+
+**Tailwind:**
+```html
+<div class="container mx-auto px-4 max-w-screen-xl">
+  Content
+</div>
+```
+
+**ClasshSS:**
+```haskell
+$(classh'
+  [ custom .~ "container"  -- Use Tailwind's container class
+  , mx .~~ TWSize_Auto
+  , px .~~ TWSize 4
+  , maxW .~~ TWSize_Screen
+  ])
+```
+
+### Responsive Grid
+
+**Tailwind:**
+```html
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+  Items
+</div>
+```
+
+**ClasshSS:**
+```haskell
+$(classh'
+  [ custom .~ "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
+  ])
+```
+
+## Key Differences Summary
+
+| Aspect | Tailwind | ClasshSS |
+|--------|----------|----------|
+| **Type Safety** | None (runtime strings) | Full (compile-time) |
+| **Errors** | Appear in browser | Caught at compile-time |
+| **Responsive** | `md:text-lg` | `text_size .|~ [SM, Base, LG]` |
+| **Hover** | `hover:bg-blue-700` | `bgColor .~^ [("hover", Blue C700 ...)]` |
+| **Transitions** | Manual classes | Built into state changes |
+| **Flexbox** | Full support | Use `custom` field |
+| **Custom values** | `w-[400px]` | `w .~~ pix 400` |
+| **Color shades** | `-100` to `-900` | `C100` to `C900` |
+
+## Advantages of ClasshSS
+
+1. **No typos** - `bg-blue-50` vs `bg-blue-500`? Compiler catches it
+2. **No conflicts** - Can't set `pt` and `py` together (compile error)
+3. **Better IDE support** - Type-driven autocomplete
+4. **Refactoring safe** - Rename, extract, compose with Haskell tools
+5. **Per-property transitions** - Each property can have its own transition
+6. **Explicit** - No magic, clear what's happening
+
+## Migration Strategy
+
+### Step 1: Start Small
+Begin with simple components (buttons, cards) before tackling complex layouts.
+
+### Step 2: Keep Tailwind for Layout
+Use `custom` field for complex flexbox/grid layouts initially:
+```haskell
+custom .~ "flex flex-col md:flex-row gap-4"
+```
+
+### Step 3: Learn the Operators
+- `.~~` for constants
+- `.|~` for responsive
+- `.~^` for states
+- `.~` for custom
+
+### Step 4: Use the Mapping Table
+Keep the [Tailwind Mapping Reference](reference/TAILWIND_MAPPING.md) handy for quick lookups.
+
+### Step 5: Leverage Type Safety
+Let the compiler guide you - if something doesn't compile, it's usually a good thing!
+
+## Common Pitfalls
+
+### 1. Forgetting noTransition
+
+**Wrong:**
+```haskell
+bgColor .~^ [("def", Blue C500), ("hover", Blue C700)]
+```
+
+**Right:**
+```haskell
+bgColor .~^ [("def", noTransition (Blue C500)), ("hover", Blue C700 `withTransition` Duration_300)]
+```
+
+### 2. Setting Conflicting Properties
+
+**Wrong:**
+```haskell
+$(classh' [ pt .~~ TWSize 4, py .~~ TWSize 2 ])  -- COMPILE ERROR
+```
+
+`py` sets both `pt` and `pb`, so setting `pt` separately conflicts.
+
+**Right:**
+```haskell
+$(classh' [ pt .~~ TWSize 4, pb .~~ TWSize 2 ])
+```
+
+### 3. Wrong List Length for Responsive
+
+You can provide fewer than 6 values, but be aware of what you're doing:
+```haskell
+-- This works - remaining breakpoints inherit last value
+text_size .|~ [SM, Base, LG]
+
+-- Mobile: SM, sm: Base, md: LG, lg+: LG
+```
+
+## Next Steps
+
+- **[Complete Tailwind Mapping](reference/TAILWIND_MAPPING.md)** - Comprehensive class mapping table
+- **[Operator Reference](reference/OPERATOR_REFERENCE.md)** - All operators explained
+- **[Examples](examples/)** - See ClasshSS in action
+- **[Core Concepts](core-concepts/)** - Deep dive into ClasshSS features
+
+Welcome to type-safe styling! 🎨

From 4bd8e19b1328291038b20c37fcef79b674a0701e Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Sun, 22 Feb 2026 18:30:35 -0500
Subject: [PATCH 20/29] feat: add type-safe gradient support for bgColor

- Add GradientColor type (SolidColor | GradientColor)
- Add GradientDirection, ColorStop, StopPosition types
- Add helper functions: solidColor, linearGradient, linearGradientVia, etc.
- Support stop positions (from-10%, via-30%, to-90%)
- Fix responsive/state prefix application for multi-class gradients
- Add gradient-test suite (13 tests)

BREAKING CHANGE: bgColor now requires GradientColor type.
Use solidColor wrapper for simple colors:
  bgColor .~~ solidColor (Blue C500)
---
 ClasshSS.cabal             |  13 +
 src/Classh.hs              | 608 ++++++++++++++++++++++++++++++++++---
 src/Classh/Box.hs          | 416 ++++++++++++++++++++++---
 src/Classh/Box/Gradient.hs | 241 +++++++++++++++
 src/Classh/Text.hs         | 299 ++++++++++++++++--
 test/GradientTest.hs       | 175 +++++++++++
 6 files changed, 1649 insertions(+), 103 deletions(-)
 create mode 100644 src/Classh/Box/Gradient.hs
 create mode 100644 test/GradientTest.hs

diff --git a/ClasshSS.cabal b/ClasshSS.cabal
index b00be03..4bf395d 100644
--- a/ClasshSS.cabal
+++ b/ClasshSS.cabal
@@ -34,6 +34,7 @@ library
                      Classh.Box
                      Classh.Box.Border
                      Classh.Box.DivInt
+                     Classh.Box.Gradient
                      Classh.Box.Margin
                      Classh.Box.Padding
                      Classh.Box.Placement
@@ -164,3 +165,15 @@ test-suite transform-test
                     , lens
                     , text
     default-language: Haskell2010
+
+test-suite gradient-test
+    import:           warnings
+    type:             exitcode-stdio-1.0
+    hs-source-dirs:   test
+    main-is:          GradientTest.hs
+    build-depends:    base
+                    , ClasshSS
+                    , data-default
+                    , lens
+                    , text
+    default-language: Haskell2010
diff --git a/src/Classh.hs b/src/Classh.hs
index 282ad33..62c008f 100644
--- a/src/Classh.hs
+++ b/src/Classh.hs
@@ -14,55 +14,311 @@
 --  Stability   :  provisional
 --  Portability :  portable
 --
--- This module exports all modules in the ClasshSS package
+--  ClasshSS: Type-safe CSS-in-Haskell based on Tailwind CSS.
 --
--- The majority of classes in Tailwind are either to handle
--- 1) Elements/Boxes
--- 2) Text
+--  = Overview
 --
--- That said, here is a common real example creating a box with some text in it, using reflex-dom to illustrate
+--  ClasshSS provides a type-safe interface to Tailwind CSS classes with compile-time
+--  validation. It prevents common mistakes like conflicting class definitions and
+--  ensures your styles are valid before runtime.
 --
--- > elClass "div" $(classh' [ padding . t .~~ pix 20, bgColor .~~ Gray C300 ]) $ do
--- >    textS $(classh' [text_size .|~ [XL,XL2]]) "Hey"
+--  The library revolves around two main configuration types:
 --
--- Using Classh.Shorthand functions we can make this more ergonomic/take up less space
+--  * 'BoxConfig' - For styling HTML elements (layout, colors, borders, shadows, transforms)
+--  * 'TextConfigTW' - For text styling (font, size, weight, color, decoration)
 --
--- for example
+--  = Quick Start
 --
--- > padding . t == pt
+--  A simple example creating a styled box with text using reflex-dom:
 --
--- The above divs we have created ensure there is no 'classhes'. For example, if we set the top padding but also the
--- y-padding then it will complain at compile time. Hence, the `$(..)` Template Haskell syntax. You can avoid this by
--- using classhUnsafe without this TH syntax
+--  @
+--  {-# LANGUAGE TemplateHaskell #-}
+--  import Classh
+--  import Reflex.Dom.Core
 --
--- `classh'` is used twice in our example, once for the div/box and once for Text as its based on the
--- CompileStyle type class which simply allows us to apply mutations to a base 'config'. When we use classh'
--- we use the default value for this type (see Data.Default) however we can use `classh` to pass in a default here
--- instead:
+--  main :: IO ()
+--  main = mainWidget $ do
+--    elClass "div" $(classh' [ pt .~~ TWSize 20, bgColor .~~ Gray C300 ]) $ do
+--      textS $(classh' [text_size .|~ [XL, XL2]]) "Hello, ClasshSS!"
+--  @
 --
--- > $(classh myBaseTextConfig [text_size .|~ [XL,XL2]])
+--  This generates type-checked Tailwind classes: @\"pt-20 bg-gray-300\"@ for the div
+--  and responsive text sizing for the content.
 --
--- Here we use the text_size lens to set the _text_size field. to XL and XL2 which are of the type TextSize
--- We have also set these properties in two different ways here
+--  = Comprehensive Example
 --
--- > 1) (.|~)
--- > 2) (.~~)
+--  A complete example showing all ClasshSS features in a styled card component:
 --
--- .|~ takes a list that goes from mobile (less than 640px) -> sm -> md -> lg -> xl -> 2xl (eg. padding)
--- .~~ takes a singular value for all screen sizes (eg. background color / bgColor)
--- The reason is because almost all properties are (WhenTW prop) which is a list of values by screen size
--- this is based on https://tailwindcss.com/docs/responsive-design
+--  @
+--  {-# LANGUAGE TemplateHaskell #-}
 --
--- We also have
+--  module Example where
 --
--- > (.~)
--- > -- which is mainly used for `custom` as the associated Record field is not a WhenTW but a String. this is just a simple setter
+--  import Classh
+--  import Reflex.Dom.Core
+--  import Reflex.Classh (textS, textPosition)  -- Note: from reflex-classh package
 --
--- > (.~+)
--- > -- appends the chosen value to what exists (perhaps in a default config)
+--  -- Complete example: styled card with positioned text
+--  exampleCard :: (DomBuilder t m, PostBuild t m) => m ()
+--  exampleCard =
+--    -- BoxConfig: All element-level styling
+--    elClass \"div\" $(classh'
+--      [ -- Colors
+--        bgColor .~~ White
+--      , border . bColor . all .~~ Gray C200
+--
+--      , -- Spacing
+--        p .~~ TWSize 6
+--      , m .~~ TWSize 4
+--
+--      , -- Shape
+--        br .~~ R_Lg
+--      , border . bWidth . all .~~ B1
+--
+--      , -- Shadow & hover effect
+--        shadow .~^ [ (\"def\", noTransition Shadow_Sm)
+--                   , (\"hover\", Shadow_Lg \`withTransition\` Duration_300)
+--                   ]
+--
+--      , -- Transform on hover
+--        transform . scale .~^ [ (\"def\", noTransition Scale_100)
+--                              , (\"hover\", Scale_105 \`withTransition\` Duration_200)
+--                              ]
+--
+--      , -- Grid positioning (NOT flex - avoid flexbox)
+--        colStart .~~ 2
+--      , colSpan .~~ 4
+--
+--      , -- Cursor
+--        cursor .~~ CursorPointer
+--      ]) $ do
+--        -- TextConfigTW: Text styling via textS (from reflex-classh)
+--        textS $(classhText
+--          [ text_color .~~ Gray C900
+--          , text_size .~~ TextXl
+--          , text_weight .~~ FontBold
+--          ]) \"Card Title\"
+--
+--        -- TextPosition: Position text (from reflex-classh)
+--        el \"p\" $ textPosition $(classhTextPos
+--          [ textAlign .~~ TextCenter
+--          , textTransform .~~ Uppercase
+--          ]) $ text \"Centered uppercase text\"
+--
+--        -- More content with separate styling
+--        textS $(classhText
+--          [ text_color .~~ Gray C600
+--          , text_size .~~ TextSm
+--          ]) \"Card description text\"
+--  @
+--
+--  __Key Concepts Shown:__
+--
+--  * BoxConfig applied to div via @classh'@
+--  * TextConfigTW applied via @textS@ (from @reflex-classh@ package)
+--  * TextPosition via @textPosition@ (from @reflex-classh@ package)
+--  * Type separation: Cannot mix BoxConfig and TextConfigTW in the same @classh'@ call
+--  * Responsive values with @.|~@ (not shown here - see docs)
+--  * State-based transitions with @.~^@ (shadow, transform)
+--  * Grid positioning (avoiding flexbox)
+--  * Transform composition
+--
+--  For the full example with detailed explanations, see @docs\/EXAMPLE.md@.
+--
+--  = Template Haskell Functions
+--
+--  ClasshSS provides several Template Haskell functions for compile-time class generation:
+--
+--  * 'classh'' - Apply mutations to default config (most common)
+--  * 'classh' - Apply mutations to custom base config
+--  * 'classhUnsafe' - Runtime version without compile-time checking
+--  * 'classhV'' - Single mutation variant of classh'
+--  * 'classhV' - Single mutation variant of classh
+--
+--  == classh' - Default Config
+--
+--  Use when starting from scratch with no base configuration:
+--
+--  @
+--  buttonClasses :: Text
+--  buttonClasses = $(classh'
+--    [ bgColor .~~ Blue C500
+--    , px .~~ TWSize 6
+--    , py .~~ TWSize 3
+--    , br .~~ R_Md
+--    ])
+--  -- Compiles to: \"bg-blue-500 px-6 py-3 rounded-md\"
+--  @
+--
+--  == classh - Custom Base Config
+--
+--  Use when you have a base theme or default configuration:
+--
+--  @
+--  myTheme :: BoxConfig
+--  myTheme = def & bgColor .~~ Gray C50 & p .~~ TWSize 4
+--
+--  customBox :: Text
+--  customBox = $(classh myTheme
+--    [ bgColor .~~ Blue C100  -- Overrides theme background
+--    , br .~~ R_Lg
+--    ])
+--  @
+--
+--  == classhUnsafe - Runtime Generation
+--
+--  Use when you need runtime arguments (no compile-time checking):
+--
+--  @
+--  dynamicClasses :: Color -> Text
+--  dynamicClasses color = classhUnsafe [bgColor .~~ color]
+--  @
+--
+--  = Operators
+--
+--  ClasshSS provides ergonomic operators for setting properties:
+--
+--  == .~~ (Set Constant)
+--
+--  Sets a value for all screen sizes:
+--
+--  @
+--  bgColor .~~ Blue C500    -- bg-blue-500
+--  br .~~ R_3Xl             -- rounded-3xl
+--  shadow .~~ Shadow_Md     -- shadow-md
+--  @
+--
+--  == .|~ (Set Responsive)
+--
+--  Sets responsive values for each breakpoint [mobile, sm, md, lg, xl, 2xl]:
+--
+--  @
+--  w .|~ [TWSize' (TWSize 12), TWSize' (TWSize 24), TWSize' (TWSize 48)]
+--  -- mobile: w-12, sm: w-24, md: w-48
+--
+--  text_size .|~ [Base, LG, XL, XL2]
+--  -- mobile: text-base, sm: text-lg, md: text-xl, lg: text-2xl
+--  @
+--
+--  == .~^ (Set with Transitions)
+--
+--  Sets stateful values (hover, focus, etc.) with transitions:
+--
+--  @
+--  bgColor .~^
+--    [ (\"def\", noTransition (Blue C600))
+--    , (\"hover\", Blue C400 \`withTransition\` Duration_300 \`withTiming\` Ease_InOut)
+--    ]
+--  @
+--
+--  Available states: @\"def\"@, @\"hover\"@, @\"focus\"@, @\"active\"@
+--
+--  == .~ (Simple Setter)
+--
+--  Direct lens setter, mainly for the @custom@ field:
+--
+--  @
+--  custom .~ \"flex items-center gap-4\"
+--  @
+--
+--  == Additional Operators
+--
+--  * '.~+' - Append to existing WhenTW list
+--  * '.++' - Extend with single conditional value
+--  * '.|+' - Append responsive values to existing
+--
+--  = Shorthand Helpers
+--
+--  ClasshSS provides Tailwind-style shorthand for common properties:
+--
+--  @
+--  -- Instead of: padding . t .~~ TWSize 4
+--  pt .~~ TWSize 4
+--
+--  -- Instead of: border . radius . allS .~~ R_Md
+--  br .~~ R_Md
+--
+--  -- Instead of: border . bWidth . allS .~~ B2
+--  bw .~~ B2
+--  @
+--
+--  Common shortcuts:
+--
+--  * Padding: 'pt', 'pb', 'pl', 'pr', 'px', 'py', 'p'
+--  * Margin: 'mt', 'mb', 'ml', 'mr', 'mx', 'my', 'm'
+--  * Border radius: 'br', 'br_t', 'br_b', 'br_l', 'br_r'
+--  * Border width: 'bw', 'bw_t', 'bw_b', 'bw_l', 'bw_r'
+--  * Border color: 'bc', 'bc_t', 'bc_b', 'bc_l', 'bc_r'
+--  * Sizing: 'w', 'h', 'maxW', 'maxH', 'minW', 'minH'
+--
+--  = Common Use Cases
+--
+--  == Responsive Button
+--
+--  @
+--  $(classh'
+--    [ bgColor .~^ [(\"def\", noTransition (Blue C500)), (\"hover\", Blue C600 \`withTransition\` Duration_300)]
+--    , px .|~ [TWSize 4, TWSize 6, TWSize 8]  -- Responsive padding
+--    , py .|~ [TWSize 2, TWSize 3, TWSize 4]
+--    , br .~~ R_Md
+--    , shadow .~^ [(\"def\", noTransition Shadow_Sm), (\"hover\", Shadow_Md \`withTransition\` Duration_200)]
+--    ])
+--  @
+--
+--  == Card Component
+--
+--  @
+--  $(classh'
+--    [ bgColor .~~ White
+--    , br .~~ R_Lg
+--    , shadow .~~ Shadow_Lg
+--    , p .~~ TWSize 6
+--    , border . bWidth . allS .~~ B1
+--    , border . bColor . allS .~~ Gray C200
+--    ])
+--  @
+--
+--  == Centered Container
+--
+--  @
+--  $(classh'
+--    [ w .~~ TWFraction 11 D12  -- 11/12 width
+--    , mx .~~ TWSize_Auto       -- Center horizontally
+--    , p .~~ TWSize 8
+--    ])
+--  @
+--
+--  = Compile-Time Safety
+--
+--  ClasshSS catches errors at compile-time:
+--
+--  @
+--  -- ERROR: pt and py overlap (py sets both pt and pb)
+--  $(classh' [ pt .~~ TWSize 4, py .~~ TWSize 2 ])
+--
+--  -- ERROR: Duplicate screen condition
+--  $(classh' [ bgColor .~^ [(\"hover\", Blue C500), (\"hover\", Blue C600)] ])
+--  @
+--
+--  The Template Haskell syntax @$(...)@ enables this validation. For runtime generation
+--  without checking, use 'classhUnsafe'.
+--
+--  = See Also
+--
+--  * "Classh.Box" - BoxConfig type and all box styling properties
+--  * "Classh.Text" - TextConfigTW type and text styling properties
+--  * "Classh.Setters" - Detailed operator documentation
+--  * "Classh.Shorthand" - All shorthand helper functions
+--  * "Classh.WithTransition" - Transition system for smooth animations
+--  * "Classh.Responsive.WhenTW" - Responsive design system
+--
+--  For comprehensive guides, see:
+--
+--  * @docs/GETTING_STARTED.md@ - Step-by-step tutorial
+--  * @docs/MIGRATION_FROM_TAILWIND.md@ - For Tailwind CSS users
+--  * @docs/core-concepts/OPERATORS.md@ - Complete operator reference
+--  * @docs/examples/@ - Real-world component examples
 --
--- > (.|+)
--- > -- like .|~ except that it adds to what already exists (perhaps in a default config)
 --------------------------------------------------------------------------------
 
 module Classh
@@ -177,50 +433,312 @@ type CompiledClassh = Compiled Expression
 defaultClasses :: T.Text
 defaultClasses = ""
 
--- | Apply mutations to BoxConfig or TextConfigTW at compile time with a default
--- > $(classh def' [ bgColor .~~ Black ]) :: Text
--- > $(classh def' [ text_color .~~ Black ]) :: Text
+-- | Apply mutations to a base config at compile-time with validation.
+--
+-- This is the primary function for creating CSS classes with a custom base configuration.
+-- It performs compile-time validation to catch errors like duplicate screen conditions
+-- or conflicting property settings.
+--
+-- === Examples
+--
+-- Basic usage with custom base:
+--
+-- @
+-- myTheme :: BoxConfig
+-- myTheme = def & bgColor .~~ Gray C50 & p .~~ TWSize 4
+--
+-- customBox :: Text
+-- customBox = $(classh myTheme
+--   [ bgColor .~~ Blue C100  -- Override theme background
+--   , br .~~ R_Lg            -- Add border radius
+--   ])
+-- @
+--
+-- With TextConfigTW:
+--
+-- @
+-- myTextTheme :: TextConfigTW
+-- myTextTheme = def & text_color .~~ Gray C900 & text_weight .~~ Normal
+--
+-- headingClasses :: Text
+-- headingClasses = $(classh myTextTheme
+--   [ text_size .~~ XL3
+--   , text_weight .~~ Bold  -- Override theme weight
+--   ])
+-- @
+--
+-- === Compile-Time Errors
+--
+-- @
+-- -- ERROR: pt and py conflict (py sets both pt and pb)
+-- $(classh def [ pt .~~ TWSize 4, py .~~ TWSize 2 ])
+--
+-- -- ERROR: Duplicate \"hover\" condition
+-- $(classh def [ bgColor .~^ [(\"hover\", Blue C500), (\"hover\", Red C500)] ])
+-- @
+--
+-- @since 0.1.0.0
 classh :: CompileStyle s => s -> [(s -> s)] -> Q Exp
 classh base muts = case compileS $ foldl (\acc f -> f acc) base muts of
   Left e -> fail $ T.unpack e
   Right styleString -> [| styleString |]
 
--- | Apply mutations to BoxConfig or TextConfigTW at compile time
--- > $(classh' [ bgColor .~~ Black ]) :: Text
--- > $(classh' [ text_color .~~ Black ]) :: Text
+-- | Apply mutations to default config at compile-time with validation.
+--
+-- This is the most commonly used function for generating CSS classes. It starts with
+-- the default configuration ('def') and applies your mutations with compile-time checking.
+--
+-- === Examples
+--
+-- Simple box styling:
+--
+-- @
+-- $(classh'
+--   [ bgColor .~~ Blue C500
+--   , p .~~ TWSize 8
+--   , br .~~ R_Md
+--   ])
+-- -- Result: \"bg-blue-500 p-8 rounded-md\"
+-- @
+--
+-- Responsive design:
+--
+-- @
+-- $(classh'
+--   [ w .|~ [TWSize' (TWSize 12), TWSize' (TWSize 24), TWSize' (TWSize 48)]
+--   , bgColor .|~ [Gray C100, Gray C200, Gray C300]
+--   ])
+-- -- Result: \"w-12 sm:w-24 md:w-48 bg-gray-100 sm:bg-gray-200 md:bg-gray-300\"
+-- @
+--
+-- With hover effects:
+--
+-- @
+-- $(classh'
+--   [ bgColor .~^ [ (\"def\", noTransition (Blue C500))
+--                 , (\"hover\", Blue C600 \`withTransition\` Duration_300)
+--                 ]
+--   ])
+-- @
+--
+-- Text styling:
+--
+-- @
+-- $(classh'
+--   [ text_size .~~ XL2
+--   , text_weight .~~ Bold
+--   , text_color .~~ Gray C900
+--   ])
+-- -- Result: \"text-2xl font-bold text-gray-900\"
+-- @
+--
+-- === Type Inference
+--
+-- The return type is inferred from usage context. Works with both BoxConfig and TextConfigTW:
+--
+-- @
+-- boxClasses :: Text
+-- boxClasses = $(classh' [ bgColor .~~ Blue C500 ])
+--
+-- textClasses :: Text
+-- textClasses = $(classh' [ text_color .~~ Blue C500 ])
+-- @
+--
+-- @since 0.1.0.0
 classh' :: (Default s, CompileStyle s) => [(s -> s)] -> Q Exp
 classh' muts = case compileS $ foldl (\acc f -> f acc) def muts of
   Left e -> fail $ T.unpack e
   Right styleString -> [| styleString |]
 
--- | Doesn't use TemplateHaskell, this is meant for making lib functions since we need args
--- from outside the would-be TH context
--- > (classhUnsafe [ bgColor .~~ Black ])
--- > (classhUnsafe [ text_color .~~ Black ])
+-- | Runtime class generation without Template Haskell.
+--
+-- Use this when you need runtime arguments that can't be known at compile-time.
+-- Note: This skips compile-time validation, so errors will only appear at runtime.
+--
+-- === When to Use
+--
+-- * When creating library functions that accept runtime parameters
+-- * When working with dynamic values from user input
+-- * When integrating with Reflex.Dom's 'Dynamic' types
+--
+-- === Examples
+--
+-- Dynamic color based on input:
+--
+-- @
+-- coloredBox :: Color -> Text
+-- coloredBox color = classhUnsafe [ bgColor .~~ color, p .~~ TWSize 4 ]
+--
+-- -- Usage:
+-- coloredBox (Blue C500)  -- \"bg-blue-500 p-4\"
+-- coloredBox (Red C600)   -- \"bg-red-600 p-4\"
+-- @
+--
+-- With Reflex.Dom Dynamic:
+--
+-- @
+-- dynClasses <- holdDyn (classhUnsafe [bgColor .~~ Gray C300]) updateEvent
+-- elDynClass \"div\" dynClasses $ text \"Dynamic styling\"
+-- @
+--
+-- In reusable components:
+--
+-- @
+-- styledButton :: Text -> BoxConfig -> m ()
+-- styledButton label customConfig = do
+--   let classes = classhUnsafe [id]  -- Apply custom config
+--   elClass \"button\" (boxCSS customConfig) $ text label
+-- @
+--
+-- === Drawbacks
+--
+-- * No compile-time validation
+-- * Can't catch conflicting properties or duplicate conditions
+-- * Slightly less performant (runtime string generation)
+--
+-- @since 0.1.0.0
 classhUnsafe :: (Default a, ShowTW a) => [a -> a] -> T.Text
 classhUnsafe muts = showTW $ def `applyFs` muts
 
---classhV, classhV' :: Q Exp
+-- | Single-mutation variant of 'classh'.
+--
+-- Convenience function for applying exactly one mutation to a base config.
+--
+-- === Examples
+--
+-- @
+-- -- Instead of:
+-- $(classh myTheme [ bgColor .~~ Blue C500 ])
+--
+-- -- You can write:
+-- $(classhV myTheme (bgColor .~~ Blue C500))
+-- @
+--
+-- @since 0.1.0.0
 classhV :: (CompileStyle a) => a -> (a -> a) -> Q Exp
 classhV base mutation = classh base [mutation]
 
+-- | Single-mutation variant of 'classh''.
+--
+-- Convenience function for applying exactly one mutation to the default config.
+--
+-- === Examples
+--
+-- @
+-- -- Instead of:
+-- $(classh' [ bgColor .~~ Blue C500 ])
+--
+-- -- You can write:
+-- $(classhV' (bgColor .~~ Blue C500))
+-- @
+--
+-- @since 0.1.0.0
 classhV' :: (Default a, CompileStyle a) => (a -> a) -> Q Exp
 classhV' mutation = classh' [mutation]
 
 
--- | Synonym to showTW
+-- | Synonym for 'showTW' specialized to BoxConfig.
+--
+-- Converts a BoxConfig to its Tailwind CSS class string representation.
+-- Useful when you already have a constructed BoxConfig value.
+--
+-- === Examples
+--
+-- @
+-- myBox :: BoxConfig
+-- myBox = def & bgColor .~~ Blue C500 & p .~~ TWSize 4
+--
+-- classes :: Text
+-- classes = boxCSS myBox
+-- -- Result: \"bg-blue-500 p-4\"
+-- @
+--
+-- @since 0.1.0.0
 boxCSS :: BoxConfig -> T.Text
 boxCSS = showTW
 
+-- | Append BoxConfig mutations to an existing class string.
+--
+-- Useful for extending a base set of classes with additional styling.
+--
+-- === Examples
+--
+-- @
+-- baseClasses :: Text
+-- baseClasses = \"container mx-auto\"
+--
+-- extendedClasses :: Text
+-- extendedClasses = alsoF baseClasses [ bgColor .~~ Blue C50, p .~~ TWSize 8 ]
+-- -- Result: \"container mx-auto bg-blue-50 p-8\"
+-- @
+--
+-- @since 0.1.0.0
 alsoF :: T.Text -> [BoxConfig -> BoxConfig] -> T.Text
 alsoF s cfgMuts = s <> boxCSS (def `applyFs` cfgMuts)
 
+-- | Append a BoxConfig to an existing class string.
+--
+-- Similar to 'alsoF' but takes a constructed BoxConfig instead of mutations.
+--
+-- === Examples
+--
+-- @
+-- baseClasses :: Text
+-- baseClasses = \"container mx-auto\"
+--
+-- additionalConfig :: BoxConfig
+-- additionalConfig = def & bgColor .~~ Blue C50 & p .~~ TWSize 8
+--
+-- combined :: Text
+-- combined = also baseClasses additionalConfig
+-- -- Result: \"container mx-auto bg-blue-50 p-8\"
+-- @
+--
+-- @since 0.1.0.0
 also :: T.Text -> BoxConfig -> T.Text
 also s cfg = s <> boxCSS cfg
 
+-- | Apply a list of functions to a value in sequence.
+--
+-- This is a helper function used internally by ClasshSS to apply
+-- mutations to configurations. Left fold over the functions.
+--
+-- === Examples
+--
+-- @
+-- result = applyFs def
+--   [ bgColor .~~ Blue C500
+--   , p .~~ TWSize 4
+--   , br .~~ R_Md
+--   ]
+-- @
+--
+-- @since 0.1.0.0
 applyFs :: a -> [a -> a] -> a
 applyFs in_ fs = foldl (\acc f -> f acc) in_ fs
 
+-- | Collection of config mutations that can be applied together.
+--
+-- Useful for grouping related styling mutations that are frequently used together.
+--
+-- === Examples
+--
+-- @
+-- buttonBase :: ClassCollection BoxConfig
+-- buttonBase = ClassCollection
+--   [ px .~~ TWSize 6
+--   , py .~~ TWSize 3
+--   , br .~~ R_Md
+--   , text_weight .~~ Bold
+--   ]
+--
+-- primaryButton :: Text
+-- primaryButton = $(classh' $
+--   getCollection buttonBase ++
+--   [ bgColor .~~ Blue C500 ])
+-- @
+--
+-- @since 0.1.0.0
 newtype ClassCollection tw = ClassCollection { getCollection :: [tw -> tw] }
 
 -- END OF MODULE
diff --git a/src/Classh/Box.hs b/src/Classh/Box.hs
index 671c945..a0aae46 100644
--- a/src/Classh/Box.hs
+++ b/src/Classh/Box.hs
@@ -11,42 +11,292 @@
 --  Stability   :  provisional
 --  Portability :  portable
 --
---  The core interface to creating responsive elements, including images.  
+--  BoxConfig: The core type for styling HTML elements (divs, sections, images, etc.).
 --
---  Here is a common real example creating a box with some text in it, using reflex-dom to illustrate
+--  = Overview
 --
--- > elClass "div" $(classh' [ padding . t .~~ pix 20, bgColor .~~ Gray C300 ]) $ do
--- >    text "Hey"
+--  This module provides 'BoxConfig', the primary configuration type for styling
+--  HTML elements in ClasshSS. It encompasses all visual properties except text-specific
+--  styling (which uses 'Classh.Text.TextConfigTW').
 --
---  This module and all modules which it re-exports are your interface to writing typified classes
---  specifically for Box's ( Box == element )
+--  BoxConfig includes:
 --
--- Using Classh.Shorthand functions we can make this more ergonomic/take up less space
+--  * Layout - Grid positioning, sizing, constraints
+--  * Spacing - Padding and margin with responsive support
+--  * Colors - Background colors and opacity (with transitions)
+--  * Borders - Radius, width, color, style, rings, outlines
+--  * Visual Effects - Shadows (with transitions)
+--  * Transforms - Rotate, scale, translate, skew (with transitions)
+--  * Positioning - Justify and align content
+--  * Cursor - Mouse cursor styles
 --
--- for example
--- > padding . t == pt
+--  = Quick Example
 --
--- The above divs we have created ensure there is no \'classhes\'. For example, if we set the top padding but also the
--- y-padding then it will complain at compile time. Hence, the `$(..)` Template Haskell syntax. You can avoid this by
--- using classhUnsafe without this TH syntax. Classh's type system also enforces that you cannot use text config setters
--- in the same classh expression as one with 'BoxConfig' setters. This is due to the design goal to reduce spooky behavior
--- and misleading code. For example if we have multiple parent divs with text classes, then it will make it challenging to
--- find why a given piece of text appears as such, especially if we refactor components, the reason for its appearance would
--- be even more hidden 
+--  Creating a styled card with Reflex.Dom:
 --
--- Note that we can also use '.|~' and 'zipScreens' to easily create responsive boxes 
--- .|~ takes a list that goes from mobile (less than 640px) -> sm -> md -> lg -> xl -> 2xl (eg. padding) 
--- .~~ takes a singular value for all screen sizes (eg. background color / bgColor) 
--- The reason is because almost all properties are (WhenTW prop) which is a list of values by screen size 
--- this is based on https://tailwindcss.com/docs/responsive-design
+--  @
+--  elClass \"div\" $(classh'
+--    [ bgColor .~~ White
+--    , p .~~ TWSize 6
+--    , br .~~ R_Lg
+--    , shadow .~~ Shadow_Lg
+--    , border . bWidth . allS .~~ B1
+--    , border . bColor . allS .~~ Gray C200
+--    ]) $ do
+--      text \"Card content here\"
+--  @
 --
--- We also have
--- (.~) which is mainly used for `custom` as the associated Record field is not a WhenTW but a String.
--- this is just a simple setter 
--- (.~+) appends the chosen value to what exists (perhaps in a default config)
--- (.|+) like .|~ except that it adds to what already exists (perhaps in a default config)
+--  = BoxConfig Fields
+--
+--  == Grid Layout
+--
+--  * '_colStart' - Grid column start position (1-12)
+--  * '_colSpan' - Grid column span (1-12)
+--
+--  @
+--  $(classh' [ colStart .~~ 2, colSpan .~~ 4 ])
+--  -- Result: \"col-start-2 col-span-4\"
+--  @
+--
+--  == Background
+--
+--  * '_bgColor' - Background color (transitionable)
+--  * '_bgOpacity' - Background opacity 1-100 (transitionable, default 100)
+--
+--  @
+--  -- Simple background
+--  bgColor .~~ Blue C500
+--
+--  -- With hover transition
+--  bgColor .~^ [ (\"def\", noTransition (Blue C500))
+--              , (\"hover\", Blue C600 \`withTransition\` Duration_300)
+--              ]
+--  @
+--
+--  == Spacing
+--
+--  * '_padding' - 'BoxPadding' with individual sides (transitionable)
+--  * '_margin' - 'BoxMargin' with individual sides (transitionable)
+--
+--  @
+--  -- Using shorthand (see "Classh.Shorthand")
+--  pt .~~ TWSize 4   -- padding-top
+--  pb .~~ TWSize 4   -- padding-bottom
+--  px .~~ TWSize 6   -- padding-left and padding-right
+--  py .~~ TWSize 2   -- padding-top and padding-bottom
+--  p .~~ TWSize 4    -- all sides
+--
+--  -- Same pattern for margin: mt, mb, mx, my, m
+--  @
+--
+--  == Sizing
+--
+--  * '_sizingBand' - 'BoxSizingBand' containing width, height, min/max constraints (all transitionable)
+--
+--  @
+--  -- Using shorthand
+--  w .~~ TWSize_Full           -- width: 100%
+--  h .~~ pix 400               -- height: 400px
+--  maxW .~~ TWSize_Screen      -- max-width: 100vw
+--  minH .~~ pix 200            -- min-height: 200px
+--
+--  -- Fractional widths
+--  w .~~ TWFraction 11 D12     -- width: 11/12
+--  @
+--
+--  == Borders
+--
+--  * '_border' - 'BorderConfig' with radius, width, color, style, rings, outlines (most transitionable)
+--
+--  @
+--  -- Using shorthand
+--  br .~~ R_Lg                    -- rounded-lg (all corners)
+--  br_t .~~ R_Md                  -- rounded-t-md (top corners)
+--  bw .~~ B2                      -- border-2 (all sides)
+--  bw_t .~~ B1                    -- border-t (top only)
+--  bc .~~ Gray C300               -- border-gray-300 (all sides)
+--
+--  -- Full path for fine control
+--  border . radius . borderRadius_tr .~~ R_Lg  -- Top-right corner only
+--  border . bWidth . t .~~ B2                  -- Top border width
+--  border . bColor . allS .~~ Gray C200        -- All sides border color
+--  @
+--
+--  == Visual Effects
+--
+--  * '_shadow' - Box shadow (transitionable)
+--
+--  @
+--  shadow .~~ Shadow_Md
+--
+--  -- With hover transition
+--  shadow .~^ [ (\"def\", noTransition Shadow_Sm)
+--             , (\"hover\", Shadow_Lg \`withTransition\` Duration_200)
+--             ]
+--  @
+--
+--  == Transforms
+--
+--  * '_transform' - 'TransformConfig' with rotate, scale, translate, skew, origin (all transitionable)
+--
+--  @
+--  -- Simple rotation
+--  transform . rotate .~~ Rotate_45
+--
+--  -- Scale with hover
+--  transform . scale .~^ [ (\"def\", noTransition Scale_100)
+--                        , (\"hover\", Scale_105 \`withTransition\` Duration_300)
+--                        ]
+--
+--  -- Translation
+--  transform . translateX .~~ Translate_TWSize (TWSize 4)
+--  transform . translateY .~~ Translate_Fraction 1 D2  -- 50%
+--  @
+--
+--  == Positioning
+--
+--  * '_position' - Tuple of ('Justify', 'Align') for content positioning
+--
+--  @
+--  position .~~ (J_Center, A_Center)  -- Center content
+--  position .~~ centered              -- Shorthand for above
+--  position .~~ topLeft               -- Top-left alignment
+--  @
+--
+--  == Cursor
+--
+--  * '_cursor' - Mouse cursor style
+--
+--  @
+--  cursor .~~ CursorPointer
+--  cursor .~~ CursorNotAllowed
+--  @
+--
+--  == Custom Classes
+--
+--  * '_box_custom' - Arbitrary Tailwind classes (escape hatch)
+--
+--  @
+--  custom .~ \"flex flex-col items-center gap-4\"
+--  @
+--
+--  = Responsive Design
+--
+--  Most BoxConfig properties use 'WhenTW' for responsive values:
+--
+--  @
+--  -- Different backgrounds at each breakpoint
+--  bgColor .|~ [Gray C100, Gray C200, Gray C300, Gray C400, Gray C500, Gray C600]
+--  --          mobile    sm         md         lg         xl         2xl
+--
+--  -- Responsive padding
+--  p .|~ [TWSize 2, TWSize 4, TWSize 6, TWSize 8]
+--  --    mobile    sm         md         lg (and larger)
+--  @
+--
+--  = State-Based Styling
+--
+--  Use '.~^' for hover, focus, and other states:
+--
+--  @
+--  bgColor .~^
+--    [ (\"def\", noTransition (Blue C500))
+--    , (\"hover\", Blue C600 \`withTransition\` Duration_300)
+--    , (\"focus\", Blue C700 \`withTransition\` Duration_200)
+--    ]
+--  @
+--
+--  = Type Safety
+--
+--  BoxConfig enforces type safety at compile-time:
+--
+--  * Cannot mix BoxConfig and TextConfigTW setters in same expression
+--  * Cannot set conflicting properties (e.g., @pt@ and @py@ together)
+--  * Catches duplicate screen conditions
+--
+--  @
+--  -- COMPILE ERROR: pt and py conflict (py sets both pt and pb)
+--  $(classh' [ pt .~~ TWSize 4, py .~~ TWSize 2 ])
+--  @
+--
+--  = Common Patterns
+--
+--  == Card Component
+--
+--  @
+--  $(classh'
+--    [ bgColor .~~ White
+--    , br .~~ R_Lg
+--    , shadow .~~ Shadow_Lg
+--    , p .~~ TWSize 6
+--    , border . bWidth . allS .~~ B1
+--    , border . bColor . allS .~~ Gray C200
+--    ])
+--  @
+--
+--  == Centered Container
+--
+--  @
+--  $(classh'
+--    [ w .~~ TWFraction 11 D12
+--    , mx .~~ TWSize_Auto
+--    , p .~~ TWSize 8
+--    ])
+--  @
+--
+--  == Responsive Button
+--
+--  @
+--  $(classh'
+--    [ bgColor .~^ [(\"def\", noTransition (Blue C500)), (\"hover\", Blue C600 \`withTransition\` Duration_300)]
+--    , px .|~ [TWSize 4, TWSize 6, TWSize 8]
+--    , py .|~ [TWSize 2, TWSize 3, TWSize 4]
+--    , br .~~ R_Md
+--    , shadow .~^ [(\"def\", noTransition Shadow_Sm), (\"hover\", Shadow_Md \`withTransition\` Duration_200)]
+--    ])
+--  @
+--
+--  = Shorthand Helpers
+--
+--  For more ergonomic code, use shorthand from "Classh.Shorthand":
+--
+--  @
+--  -- Instead of: padding . t .~~ TWSize 20
+--  pt .~~ TWSize 20
+--
+--  -- Instead of: border . radius . allS .~~ R_Lg
+--  br .~~ R_Lg
+--  @
+--
+--  See "Classh.Shorthand" for complete list of shortcuts.
+--
+--  = Re-Exported Modules
+--
+--  This module re-exports all box-related modules for convenience:
+--
+--  * "Classh.Color" - Color types and hex colors
+--  * "Classh.Cursor" - Cursor styles
+--  * "Classh.Box.TWSize" - Size types and helpers
+--  * "Classh.Box.Padding" - Padding configuration
+--  * "Classh.Box.Margin" - Margin configuration
+--  * "Classh.Box.SizingBand" - Width/height with constraints
+--  * "Classh.Box.Placement" - Justify and Align types
+--  * "Classh.Box.Border" - Border configuration
+--  * "Classh.Box.Shadow" - Shadow types
+--  * "Classh.Box.Transition" - Transition configuration
+--  * "Classh.Box.Transform" - Transform types and configuration
+--  * "Classh.WithTransition" - Transition builder system
+--  * "Classh.Responsive.WhenTW" - Responsive value system
+--
+--  = See Also
+--
+--  * "Classh" - Main module with Template Haskell functions
+--  * "Classh.Text" - For text-specific styling
+--  * "Classh.Setters" - Operator documentation
+--  * "Classh.Shorthand" - Ergonomic shortcuts
+--  * @docs/features/BOX_STYLING.md@ - Complete feature guide
+--  * @docs/examples/@ - Real-world examples
 --
--- We can also add any arbitrary classes to the end of the TextConfigTW using its HasCustom instance
 --------------------------------------------------------------------------------
 
 
@@ -81,6 +331,7 @@ import Classh.Internal.TShow
 import Classh.Internal.TWNum as X
 import Classh.Responsive.WhenTW as X
 import Classh.Color as X
+import Classh.Box.Gradient as X
 import Classh.Cursor as X
 import Classh.Box.TWSize as X
 import Classh.Box.Padding as X
@@ -97,20 +348,72 @@ import Control.Lens hiding ((<&>), transform)
 import Data.Default
 import qualified Data.Text as T
 
+-- | Configuration type for styling HTML box elements (divs, sections, etc.).
+--
+-- BoxConfig contains all visual styling properties for HTML elements except
+-- text-specific properties (which use 'Classh.Text.TextConfigTW').
+--
+-- === Field Overview
+--
+-- * Grid: '_colStart', '_colSpan'
+-- * Background: '_bgColor' (transitionable), '_bgOpacity' (transitionable)
+-- * Spacing: '_padding' (transitionable), '_margin' (transitionable)
+-- * Sizing: '_sizingBand' (width, height, min/max - transitionable)
+-- * Borders: '_border' (radius, width, color, style, rings)
+-- * Layout: '_position' (justify, align)
+-- * Effects: '_shadow' (transitionable)
+-- * Interaction: '_cursor'
+-- * Transforms: '_transform' (rotate, scale, translate, skew - transitionable)
+-- * Escape hatch: '_box_custom'
+--
+-- === Examples
+--
+-- @
+-- -- Simple box
+-- def & bgColor .~~ Blue C500 & p .~~ TWSize 4
+--
+-- -- Card component
+-- def
+--   & bgColor .~~ White
+--   & br .~~ R_Lg
+--   & shadow .~~ Shadow_Lg
+--   & p .~~ TWSize 6
+--
+-- -- Responsive container
+-- def
+--   & w .|~ [TWSize_Full, TWSize' (TWSize 64), TWSize' (TWSize 80)]
+--   & mx .~~ TWSize_Auto
+-- @
+--
+-- @since 0.1.0.0
 data BoxConfig = BoxConfig
   { _colStart :: WhenTW Int
+    -- ^ Grid column start position (1-12). Default: empty (no grid positioning)
   , _colSpan :: WhenTW Int
-  , _bgColor :: WhenTW (WithTransition Color)  -- Transitionable!
-  , _bgOpacity :: WhenTW (WithTransition Int)  -- Transitionable! (1 5 10 .. 100 -- def == 519)
+    -- ^ Grid column span (1-12). Default: empty (no grid span)
+  , _bgColor :: WhenTW (WithTransition GradientColor)
+    -- ^ Background color or gradient (transitionable). Default: empty (no background)
+    -- Use 'solid' for simple colors, or gradient helpers like 'linearGradient'
+  , _bgOpacity :: WhenTW (WithTransition Int)
+    -- ^ Background opacity 1-100 (transitionable). Default: empty (100% opacity)
   , _padding :: BoxPadding
+    -- ^ Padding on all sides (transitionable). See 'BoxPadding' for details
   , _margin :: BoxMargin
+    -- ^ Margin on all sides (transitionable). See 'BoxMargin' for details
   , _sizingBand :: BoxSizingBand
-  , _border :: BorderConfig -- { rounded, thickness, etc .. }
+    -- ^ Width, height, and size constraints (transitionable). See 'BoxSizingBand'
+  , _border :: BorderConfig
+    -- ^ Border configuration (radius, width, color, style, rings, outlines)
   , _position :: WhenTW (Justify, Align)
-  , _shadow :: WhenTW (WithTransition BoxShadow)  -- Transitionable!
+    -- ^ Content positioning with justify and align
+  , _shadow :: WhenTW (WithTransition BoxShadow)
+    -- ^ Box shadow (transitionable). Default: empty (no shadow)
   , _cursor :: WhenTW CursorStyle
-  , _transform :: TransformConfig  -- All transform properties (rotate, scale, translate, skew, origin)
+    -- ^ Mouse cursor style. Default: empty (default cursor)
+  , _transform :: TransformConfig
+    -- ^ All CSS transforms (rotate, scale, translate, skew, origin - transitionable)
   , _box_custom :: T.Text
+    -- ^ Arbitrary custom Tailwind classes. Default: empty string
   }
   deriving Show
 
@@ -133,7 +436,7 @@ instance CompileStyle BoxConfig where
       , compileSizingBand (_sizingBand cfg)
       , compilePadding (_padding cfg)
       , compileMargin (_margin cfg)
-      , compileWithTransitionTW (_bgColor cfg) ((<>) "bg-" . showTW) Transition_Colors
+      , compileBgColor (_bgColor cfg)
       , compileWithTransitionTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow) Transition_Opacity
       , compileWithTransitionTW (_shadow cfg) showTW Transition_Shadow
       , compileWhenTW (_cursor cfg) showTW
@@ -214,7 +517,7 @@ instance ShowTW BoxConfig where
   showTW cfg = foldr (<&>) mempty
    [ renderWhenTW (_colStart cfg) ((<>) "col-start-" . tshow)
    , renderWhenTW (_colSpan cfg) ((<>) "col-span-" . tshow)
-   , renderWithTransitionTW (_bgColor cfg) ((<>) "bg-" . showTW) Transition_Colors
+   , renderBgColorTW (_bgColor cfg)
    , renderWithTransitionTW (_bgOpacity cfg) ((<>) "bg-opacity-" . tshow) Transition_Opacity
    , showTW . _border $ cfg
    , showTW . _sizingBand $ cfg
@@ -249,3 +552,48 @@ instance Semigroup BoxConfig where
     , _transform  = _transform a <> _transform b
     , _box_custom = _box_custom a <> _box_custom b
     }
+
+-- | Render a GradientColor for bgColor without any prefix.
+-- Returns the raw class(es) that need prefixing.
+renderBgColorRaw :: GradientColor -> T.Text
+renderBgColorRaw (SolidColor color) = "bg-" <> showTW color
+renderBgColorRaw (GradientColor cfg) = showTW cfg
+
+-- | Apply a prefix to each space-separated class.
+-- "hover:" "bg-gradient-to-r from-blue-500" -> "hover:bg-gradient-to-r hover:from-blue-500"
+applyPrefixToClasses :: T.Text -> T.Text -> T.Text
+applyPrefixToClasses prefix classes =
+  T.intercalate " " $ fmap (\c -> prefix <> c) $ T.words classes
+
+-- | Custom render for bgColor that handles gradient multi-class output.
+-- Gradients produce multiple space-separated classes that each need
+-- the responsive/state prefix applied.
+renderBgColorTW :: WhenTW (WithTransition GradientColor) -> T.Text
+renderBgColorTW tws = foldr (<&>) mempty $
+  fmap (\(c, WithTransition val mTransCfg) ->
+    let prefix = if c == "def" then "" else (c <> ":")
+        classes = renderBgColorRaw val
+        valueClasses = applyPrefixToClasses prefix classes
+        transitionClasses = case mTransCfg of
+          Nothing -> mempty
+          Just cfg ->
+            let cssProp = transitionPropertyToCSSName Transition_Colors
+                duration = T.drop 9 $ tshow (_transitionDuration cfg)
+                timing = transitionTimingToCSSName (_transitionTiming cfg)
+                delay = T.drop 6 $ tshow (_transitionDelay cfg)
+                transValue = cssProp <> "_" <> duration <> "ms_" <> timing <> "_" <> delay <> "ms"
+            in prefix <> "[transition:" <> transValue <> "]"
+    in valueClasses <&> transitionClasses
+  ) tws
+
+-- | Custom compile for bgColor with duplicate checking.
+compileBgColor :: WhenTW (WithTransition GradientColor) -> Either T.Text T.Text
+compileBgColor tws = case checkDuplicates $ fmap fst tws of
+  Left e -> Left e
+  Right () -> Right $ renderBgColorTW tws
+  where
+    checkDuplicates [] = Right ()
+    checkDuplicates (s:ss) =
+      if elem s ss
+      then Left $ s <> " exists twice"
+      else checkDuplicates ss
diff --git a/src/Classh/Box/Gradient.hs b/src/Classh/Box/Gradient.hs
new file mode 100644
index 0000000..fc493b7
--- /dev/null
+++ b/src/Classh/Box/Gradient.hs
@@ -0,0 +1,241 @@
+--------------------------------------------------------------------------------
+-- |
+--  Module      :  Classh.Box.Gradient
+--  Copyright   :  (c) 2024, Galen Sprout
+--  License     :  BSD-style (see end of this file)
+--
+--  Maintainer  :  Galen Sprout <galen.sprout@gmail.com>
+--  Stability   :  provisional
+--  Portability :  portable
+--
+--  Type-safe gradient support for Tailwind CSS gradients.
+--
+--  = Overview
+--
+--  This module provides 'GradientColor', a type that encompasses both solid
+--  colors and gradient configurations. It replaces 'Color' in bgColor fields,
+--  allowing gradients to be used anywhere colors are used.
+--
+--  = Quick Example
+--
+--  @
+--  -- Solid color (most common):
+--  bgColor .~~ solid acePrimary
+--
+--  -- Simple two-color gradient:
+--  bgColor .~~ linearGradient To_R (hex \"4E366C\") White
+--  -- Generates: bg-gradient-to-r from-[#4E366C] to-white
+--
+--  -- Gradient with stop positions:
+--  bgColor .~~ linearGradientViaPos To_R
+--    (stopAt (hex \"4E366C\") 10)
+--    (stopAt (Pink C500) 30)
+--    (stopAt White 90)
+--  -- Generates: bg-gradient-to-r from-[#4E366C] from-10% via-pink-500 via-30% to-white to-90%
+--  @
+--
+--------------------------------------------------------------------------------
+
+module Classh.Box.Gradient
+  (
+    -- * Core Types
+    GradientColor(..)
+  , GradientConfig(..)
+  , GradientDirection(..)
+  , ColorStop(..)
+  , StopPosition(..)
+    -- * Solid Color Helper
+  , solidColor
+    -- * Color Stop Helpers
+  , stop
+  , stopAt
+    -- * Gradient Builders
+  , linearGradient
+  , linearGradientVia
+  , linearGradientPos
+  , linearGradientViaPos
+  , gradientFrom
+  ) where
+
+import Classh.Class.ShowTW
+import Classh.Color
+import Classh.Internal.TShow
+
+import Data.Default
+import qualified Data.Text as T
+
+-- | Direction for linear gradients.
+--
+-- Maps to Tailwind's gradient direction classes like @bg-gradient-to-r@.
+data GradientDirection
+  = To_T    -- ^ to top
+  | To_TR   -- ^ to top-right
+  | To_R    -- ^ to right (most common)
+  | To_BR   -- ^ to bottom-right
+  | To_B    -- ^ to bottom
+  | To_BL   -- ^ to bottom-left
+  | To_L    -- ^ to left
+  | To_TL   -- ^ to top-left
+  deriving (Show, Eq)
+
+-- | Percentage for stop positions (0-100).
+--
+-- Maps to Tailwind's position classes like @from-10%@, @via-30%@, @to-90%@.
+newtype StopPosition = StopPosition Int
+  deriving (Show, Eq)
+
+-- | A color stop with an optional position.
+--
+-- === Examples
+--
+-- @
+-- stop White              -- Just the color
+-- stopAt (Blue C500) 30   -- Color at 30%
+-- @
+data ColorStop = ColorStop
+  { _stop_color    :: Color
+  , _stop_position :: Maybe StopPosition
+  } deriving (Show, Eq)
+
+-- | Gradient configuration with direction and color stops.
+data GradientConfig = GradientConfig
+  { _gradient_direction :: GradientDirection
+  , _gradient_from      :: ColorStop           -- ^ Starting color (required)
+  , _gradient_via       :: Maybe ColorStop     -- ^ Middle color (optional)
+  , _gradient_to        :: Maybe ColorStop     -- ^ Ending color (optional)
+  } deriving (Show, Eq)
+
+-- | Union type: either a solid color or a gradient.
+--
+-- This type replaces 'Color' in '_bgColor' and similar fields, allowing
+-- both simple colors and gradients to be used interchangeably.
+data GradientColor
+  = SolidColor Color
+  | GradientColor GradientConfig
+  deriving (Show, Eq)
+
+-- | Default is transparent solid color
+instance Default GradientColor where
+  def = SolidColor Transparent
+
+instance ShowTW GradientDirection where
+  showTW To_T  = "to-t"
+  showTW To_TR = "to-tr"
+  showTW To_R  = "to-r"
+  showTW To_BR = "to-br"
+  showTW To_B  = "to-b"
+  showTW To_BL = "to-bl"
+  showTW To_L  = "to-l"
+  showTW To_TL = "to-tl"
+
+instance ShowTW StopPosition where
+  showTW (StopPosition p) = tshow p <> "%"
+
+-- | Helper to render a color stop with its position.
+-- Generates output like @from-blue-500 from-10%@ or @via-pink-500 via-30%@
+renderStop :: T.Text -> ColorStop -> T.Text
+renderStop prefix (ColorStop color mpos) =
+  prefix <> "-" <> showTW color <>
+  maybe "" (\(StopPosition p) -> " " <> prefix <> "-" <> tshow p <> "%") mpos
+
+instance ShowTW GradientConfig where
+  showTW (GradientConfig dir from mvia mto) =
+    "bg-gradient-" <> showTW dir <> " " <>
+    renderStop "from" from <>
+    maybe "" (\v -> " " <> renderStop "via" v) mvia <>
+    maybe "" (\t -> " " <> renderStop "to" t) mto
+
+instance ShowTW GradientColor where
+  showTW (SolidColor color) = showTW color
+  showTW (GradientColor cfg) = showTW cfg
+
+--------------------------------------------------------------------------------
+-- Helper Functions
+--------------------------------------------------------------------------------
+
+-- | Create a solid (non-gradient) color.
+--
+-- Use this when you want a simple background color without any gradient.
+--
+-- === Example
+--
+-- @
+-- bgColor .~~ solidColor White
+-- bgColor .~~ solidColor (Blue C500)
+-- @
+solidColor :: Color -> GradientColor
+solidColor = SolidColor
+
+-- | Create a color stop without a position.
+--
+-- @
+-- stop White  -- ColorStop White Nothing
+-- @
+stop :: Color -> ColorStop
+stop c = ColorStop c Nothing
+
+-- | Create a color stop at a specific position (0-100%).
+--
+-- @
+-- stopAt (Blue C500) 30  -- Blue at 30%
+-- @
+stopAt :: Color -> Int -> ColorStop
+stopAt c p = ColorStop c (Just $ StopPosition p)
+
+-- | Create a two-color linear gradient.
+--
+-- === Example
+--
+-- @
+-- linearGradient To_R (hex \"4E366C\") White
+-- -- Generates: bg-gradient-to-r from-[#4E366C] to-white
+-- @
+linearGradient :: GradientDirection -> Color -> Color -> GradientColor
+linearGradient dir from to = GradientColor $ GradientConfig dir (stop from) Nothing (Just $ stop to)
+
+-- | Create a three-color linear gradient with a middle color.
+--
+-- === Example
+--
+-- @
+-- linearGradientVia To_BR (Purple C500) (Pink C500) White
+-- -- Generates: bg-gradient-to-br from-purple-500 via-pink-500 to-white
+-- @
+linearGradientVia :: GradientDirection -> Color -> Color -> Color -> GradientColor
+linearGradientVia dir from via to = GradientColor $ GradientConfig dir (stop from) (Just $ stop via) (Just $ stop to)
+
+-- | Create a two-color gradient with explicit stop positions.
+--
+-- === Example
+--
+-- @
+-- linearGradientPos To_R (stopAt (hex \"4E366C\") 10) (stopAt White 90)
+-- -- Generates: bg-gradient-to-r from-[#4E366C] from-10% to-white to-90%
+-- @
+linearGradientPos :: GradientDirection -> ColorStop -> ColorStop -> GradientColor
+linearGradientPos dir from to = GradientColor $ GradientConfig dir from Nothing (Just to)
+
+-- | Create a three-color gradient with explicit stop positions.
+--
+-- === Example
+--
+-- @
+-- linearGradientViaPos To_R
+--   (stopAt (hex \"4E366C\") 10)
+--   (stopAt (Pink C500) 30)
+--   (stopAt White 90)
+-- -- Generates: bg-gradient-to-r from-[#4E366C] from-10% via-pink-500 via-30% to-white to-90%
+-- @
+linearGradientViaPos :: GradientDirection -> ColorStop -> ColorStop -> ColorStop -> GradientColor
+linearGradientViaPos dir from via to = GradientColor $ GradientConfig dir from (Just via) (Just to)
+
+-- | Create a single-color gradient that fades to transparent.
+--
+-- === Example
+--
+-- @
+-- gradientFrom To_R (hex \"4E366C\")
+-- -- Generates: bg-gradient-to-r from-[#4E366C]
+-- @
+gradientFrom :: GradientDirection -> Color -> GradientColor
+gradientFrom dir from = GradientColor $ GradientConfig dir (stop from) Nothing Nothing
diff --git a/src/Classh/Text.hs b/src/Classh/Text.hs
index af259aa..735820c 100644
--- a/src/Classh/Text.hs
+++ b/src/Classh/Text.hs
@@ -10,39 +10,250 @@
 --  Stability   :  provisional
 --  Portability :  portable
 --
---  The core interface to creating responsive text 
+--  TextConfigTW: The core type for styling text content.
 --
---  Here is a common real example creating a box with some text in it, using reflex-dom to illustrate
+--  = Overview
 --
--- > elClass "div" "" $ do
--- >    textS $(classh' [text_size .|~ [XL,XL2], text_weight .~~ Bold]) "Hey"
+--  This module provides 'TextConfigTW', the configuration type for all text-specific
+--  styling in ClasshSS. It handles typography properties like size, weight, font family,
+--  color, and decoration.
 --
---  This module and all modules which it re-exports are your interface to writing typified classes
---  specifically for text
+--  TextConfigTW includes:
 --
---  Through CompileStyle, Classh enforces that 'TextConfigTW' is a seperate expression from 'BoxConfig'
---  this is because it undeniably helps to create modularity, reduce phantom CSS behaviour and makes
---  it easy to create themes to be shared by an application. For example
+--  * Typography - Font size, weight, family, style
+--  * Colors - Text color with responsive support
+--  * Decoration - Underline, overline, strikethrough with style and thickness
+--  * Interaction - Cursor styles
 --
--- > defText = def { _text_font = Font_Custom "Sarabun" } -- perhaps we want all text to be Sarabun
--- > blueBrandTextSm someText = textS $(classh defText [ text_color .~~ Blue C950, text_size .|~ [XS,SM,Base,Lg]])
--- > elClass "div" "" $ blueBrandTextSm "Sign up now!"
+--  = Quick Example
 --
--- Note that we can use '.|~' and 'zipScreens' to easily create responsive text
--- .|~ takes a list that goes from mobile (less than 640px) -> sm -> md -> lg -> xl -> 2xl (eg. text_size) 
--- .~~ takes a singular value for all screen sizes (eg. text_weight)
--- .~ is a simple setter that expects the type of the property, so the property text_color is a WhenTW Color
--- and so if we wanted to set a color on hover, we could do:
+--  Creating styled text with Reflex.Dom:
 --
--- > $(classh' [ text_color .~ [("hover", hex "FFFFFF"), ("def", Blue C950)] ])
+--  @
+--  textS $(classh'
+--    [ text_size .~~ XL3
+--    , text_weight .~~ Bold
+--    , text_color .~~ Gray C900
+--    , text_font .~~ Font_Custom \"Sarabun\"
+--    ]) \"Hello, ClasshSS!\"
+--  @
 --
--- This will set text to white on hover, and normally otherwise "text-blue-950"
+--  = Separation from BoxConfig
 --
--- We also have
--- (.~+) appends the chosen value to what exists (perhaps in a default config)
--- (.|+) like .|~ except that it adds to what already exists (perhaps in a default config)
+--  ClasshSS enforces that 'TextConfigTW' and 'Classh.Box.BoxConfig' are used in separate
+--  expressions. This design prevents phantom CSS behavior and improves modularity:
+--
+--  @
+--  -- COMPILE ERROR: Cannot mix BoxConfig and TextConfigTW
+--  $(classh' [ bgColor .~~ Blue C500, text_size .~~ XL ])
+--
+--  -- CORRECT: Separate expressions
+--  elClass \"div\" $(classh' [ bgColor .~~ Blue C500 ]) $ do
+--    textS $(classh' [ text_size .~~ XL ]) \"Text\"
+--  @
+--
+--  = TextConfigTW Fields
+--
+--  == Typography
+--
+--  * '_text_size' - Font size from XS to XL9
+--  * '_text_weight' - Font weight from Thin to Black
+--  * '_text_font' - Font family (Sans, Serif, Mono, or custom)
+--  * '_text_style' - Italic or normal
+--
+--  @
+--  text_size .~~ XL2          -- text-2xl
+--  text_weight .~~ Bold       -- font-bold
+--  text_font .~~ Sans         -- font-sans
+--  text_style .~~ Italic      -- italic
+--  @
+--
+--  == Color
+--
+--  * '_text_color' - Text color with responsive and state support
+--
+--  @
+--  -- Simple color
+--  text_color .~~ Blue C500   -- text-blue-500
+--
+--  -- With hover
+--  text_color .~ [(\"def\", Gray C900), (\"hover\", Blue C600)]
+--  @
+--
+--  == Decoration
+--
+--  * '_text_decoration' - 'TextDecorationTW' for underline, overline, strikethrough
+--
+--  @
+--  text_decoration . textDec_line .~~ Underline
+--  text_decoration . textDec_color .~~ Blue C500
+--  text_decoration . textDec_style .~~ Wavy
+--  text_decoration . textDec_thickness .~~ Thickness_2
+--  @
+--
+--  == Cursor
+--
+--  * '_text_cursor' - Mouse cursor style
+--
+--  @
+--  text_cursor .~~ CursorPointer
+--  @
+--
+--  == Custom Classes
+--
+--  * '_text_custom' - Arbitrary Tailwind classes
+--
+--  @
+--  custom .~ \"text-center uppercase tracking-wide\"
+--  @
+--
+--  = Responsive Text
+--
+--  Use '.|~' for responsive text sizing:
+--
+--  @
+--  text_size .|~ [SM, Base, LG, XL, XL2, XL3]
+--  --            mobile sm   md  lg  xl   2xl
+--
+--  -- Result: \"text-sm sm:text-base md:text-lg lg:text-xl xl:text-2xl 2xl:text-3xl\"
+--  @
+--
+--  = Theming
+--
+--  TextConfigTW makes it easy to create reusable text themes:
+--
+--  @
+--  -- Define a theme
+--  defText :: TextConfigTW
+--  defText = def & text_font .~~ Font_Custom \"Sarabun\"
+--
+--  -- Create styled text helpers
+--  brandHeading :: Text -> Text
+--  brandHeading content =
+--    textS $(classh defText
+--      [ text_size .|~ [XL2, XL3, XL4]
+--      , text_weight .~~ Bold
+--      , text_color .~~ Blue C950
+--      ]) content
+--
+--  -- Use in components
+--  elClass \"div\" \"\" $ brandHeading \"Sign up now!\"
+--  @
+--
+--  = Common Patterns
+--
+--  == Heading
+--
+--  @
+--  $(classh'
+--    [ text_size .~~ XL3
+--    , text_weight .~~ Bold
+--    , text_color .~~ Gray C900
+--    ])
+--  @
+--
+--  == Body Text
+--
+--  @
+--  $(classh'
+--    [ text_size .~~ Base
+--    , text_weight .~~ Normal
+--    , text_color .~~ Gray C700
+--    ])
+--  @
+--
+--  == Link with Hover
+--
+--  @
+--  $(classh'
+--    [ text_color .~ [(\"def\", Blue C600), (\"hover\", Blue C800)]
+--    , text_decoration . textDec_line .~ [(\"hover\", Underline)]
+--    , text_cursor .~~ CursorPointer
+--    ])
+--  @
+--
+--  == Responsive Heading
+--
+--  @
+--  $(classh'
+--    [ text_size .|~ [XL, XL2, XL3, XL4]
+--    , text_weight .~~ Bold
+--    , text_color .|~ [Gray C800, Gray C900, Gray C950]
+--    ])
+--  @
+--
+--  = Integration with Reflex.Dom
+--
+--  ClasshSS provides helper functions for text in Reflex.Dom:
+--
+--  @
+--  import Reflex.Dom.Core
+--
+--  -- Static text with styling
+--  textS :: Text -> Text -> m ()
+--  textS classes content = elClass \"span\" classes $ text content
+--
+--  -- Usage:
+--  textS $(classh' [text_size .~~ XL, text_weight .~~ Bold]) \"Hello!\"
+--  @
+--
+--  = Size Scale
+--
+--  TextSize options (from smallest to largest):
+--
+--  @
+--  XS    -- text-xs    (0.75rem, 12px)
+--  SM    -- text-sm    (0.875rem, 14px)
+--  Base  -- text-base  (1rem, 16px)
+--  LG    -- text-lg    (1.125rem, 18px)
+--  XL    -- text-xl    (1.25rem, 20px)
+--  XL2   -- text-2xl   (1.5rem, 24px)
+--  XL3   -- text-3xl   (1.875rem, 30px)
+--  XL4   -- text-4xl   (2.25rem, 36px)
+--  XL5   -- text-5xl   (3rem, 48px)
+--  XL6   -- text-6xl   (3.75rem, 60px)
+--  XL7   -- text-7xl   (4.5rem, 72px)
+--  XL8   -- text-8xl   (6rem, 96px)
+--  XL9   -- text-9xl   (8rem, 128px)
+--  @
+--
+--  = Weight Scale
+--
+--  TextWeight options:
+--
+--  @
+--  Thin         -- font-thin (100)
+--  Extralight   -- font-extralight (200)
+--  Light        -- font-light (300)
+--  Normal       -- font-normal (400)
+--  Medium       -- font-medium (500)
+--  Semibold     -- font-semibold (600)
+--  Bold         -- font-bold (700)
+--  Extrabold    -- font-extrabold (800)
+--  Black_TextWeight -- font-black (900)
+--  @
+--
+--  = Re-Exported Modules
+--
+--  This module re-exports all text-related modules for convenience:
+--
+--  * "Classh.Color" - Color types
+--  * "Classh.Cursor" - Cursor styles
+--  * "Classh.Text.Decoration" - Text decoration configuration
+--  * "Classh.Text.FontStyle" - Italic and normal styles
+--  * "Classh.Text.Font" - Font family types
+--  * "Classh.Text.Size" - Text size types
+--  * "Classh.Text.Weight" - Font weight types
+--
+--  = See Also
+--
+--  * "Classh" - Main module with Template Haskell functions
+--  * "Classh.Box" - For element/box styling
+--  * "Classh.Setters" - Operator documentation
+--  * "Classh.Responsive.WhenTW" - Responsive value system
+--  * @docs/features/TEXT_STYLING.md@ - Complete feature guide
+--  * @docs/examples/@ - Real-world examples
 --
--- We can also add any arbitrary classes to the end of the TextConfigTW using its HasCustom instance 
 --------------------------------------------------------------------------------
 
 module Classh.Text
@@ -118,15 +329,55 @@ instance CompileStyle TextConfigTW where
 instance Default TextConfigTW where
   def = TextConfigTW def def def def def def def ""
 
+-- | Configuration type for styling text content.
+--
+-- TextConfigTW contains all text-specific styling properties. It is intentionally
+-- separate from 'Classh.Box.BoxConfig' to enforce modularity and prevent CSS conflicts.
+--
+-- === Field Overview
+--
+-- * Typography: '_text_size', '_text_weight', '_text_font', '_text_style'
+-- * Color: '_text_color'
+-- * Decoration: '_text_decoration' (underline, overline, strikethrough)
+-- * Interaction: '_text_cursor'
+-- * Escape hatch: '_text_custom'
+--
+-- === Examples
+--
+-- @
+-- -- Simple heading
+-- def & text_size .~~ XL3 & text_weight .~~ Bold
+--
+-- -- Responsive body text
+-- def
+--   & text_size .|~ [SM, Base, LG]
+--   & text_color .~~ Gray C700
+--
+-- -- Themed text with custom font
+-- def
+--   & text_font .~~ Font_Custom \"Sarabun\"
+--   & text_size .~~ Base
+--   & text_color .~~ Blue C950
+-- @
+--
+-- @since 0.1.0.0
 data TextConfigTW = TextConfigTW
   { _text_size :: WhenTW TextSize
+    -- ^ Font size (XS, SM, Base, LG, XL through XL9). Default: empty (browser default)
   , _text_weight :: WhenTW TextWeight
-  , _text_font :: WhenTW Font -- many options -- EG. Sarabun -> font-[Sarabun]
+    -- ^ Font weight (Thin through Black_TextWeight). Default: empty (browser default)
+  , _text_font :: WhenTW Font
+    -- ^ Font family (Sans, Serif, Mono, or Font_Custom \"Name\"). Default: empty (browser default)
   , _text_color :: WhenTW Color
+    -- ^ Text color. Default: empty (browser default, usually black)
   , _text_decoration :: TextDecorationTW
+    -- ^ Text decoration (underline, overline, strikethrough, color, style, thickness, offset)
   , _text_style :: WhenTW FontStyle
+    -- ^ Font style (Italic or NotItalic). Default: empty (NotItalic)
   , _text_cursor :: WhenTW CursorStyle
+    -- ^ Mouse cursor style. Default: empty (default cursor)
   , _text_custom :: T.Text
+    -- ^ Arbitrary custom Tailwind classes. Default: empty string
   }
 
 makeLenses ''TextConfigTW
diff --git a/test/GradientTest.hs b/test/GradientTest.hs
new file mode 100644
index 0000000..f5bd7cc
--- /dev/null
+++ b/test/GradientTest.hs
@@ -0,0 +1,175 @@
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module Main where
+
+import Classh
+import Classh.Class.CompileStyle
+import Control.Lens ((&))
+import Data.Default (def)
+import qualified Data.Text as T
+
+-- Test 1: Solid color renders correctly (backwards compat)
+testSolid :: BoxConfig
+testSolid = def
+  & bgColor .~~ solidColor (Blue C500)
+
+-- Test 2: Simple two-color gradient
+testLinearGradient :: BoxConfig
+testLinearGradient = def
+  & bgColor .~~ linearGradient To_R (hex "4E366C") White
+
+-- Test 3: Three-color gradient with via
+testLinearGradientVia :: BoxConfig
+testLinearGradientVia = def
+  & bgColor .~~ linearGradientVia To_BR (Purple C500) (Pink C500) White
+
+-- Test 4: Gradient with stop positions
+testGradientPositions :: BoxConfig
+testGradientPositions = def
+  & bgColor .~~ linearGradientViaPos To_R
+      (stopAt (hex "4E366C") 10)
+      (stopAt (Pink C500) 30)
+      (stopAt White 90)
+
+-- Test 5: Single color gradient (fade to transparent)
+testGradientFrom :: BoxConfig
+testGradientFrom = def
+  & bgColor .~~ gradientFrom To_R (hex "4E366C")
+
+-- Test 6: Two-color gradient with positions
+testLinearGradientPos :: BoxConfig
+testLinearGradientPos = def
+  & bgColor .~~ linearGradientPos To_B
+      (stopAt (Blue C500) 0)
+      (stopAt (Purple C500) 100)
+
+-- Test 7: Gradient with hover transition
+testGradientTransition :: BoxConfig
+testGradientTransition = def
+  & bgColor .~^ [ ("def", noTransition (solidColor (Blue C500)))
+                , ("hover", linearGradient To_R (Purple C500) (Pink C500) `withTransition` Duration_300)
+                ]
+
+-- Test 8: Responsive gradients
+testResponsiveGradient :: BoxConfig
+testResponsiveGradient = def
+  & bgColor .|~ [ solidColor (Gray C500)
+                , linearGradient To_R (Blue C500) (Purple C500)
+                ]
+
+-- Test 9: All directions
+testDirectionT :: BoxConfig
+testDirectionT = def & bgColor .~~ linearGradient To_T (Blue C500) White
+
+testDirectionTR :: BoxConfig
+testDirectionTR = def & bgColor .~~ linearGradient To_TR (Blue C500) White
+
+testDirectionBL :: BoxConfig
+testDirectionBL = def & bgColor .~~ linearGradient To_BL (Blue C500) White
+
+testDirectionL :: BoxConfig
+testDirectionL = def & bgColor .~~ linearGradient To_L (Blue C500) White
+
+testDirectionTL :: BoxConfig
+testDirectionTL = def & bgColor .~~ linearGradient To_TL (Blue C500) White
+
+testCase :: String -> BoxConfig -> T.Text -> IO Bool
+testCase name cfg expected = do
+  putStrLn $ "\n" ++ replicate 80 '-'
+  putStrLn $ "TEST: " ++ name
+  putStrLn $ replicate 80 '-'
+  case compileS cfg of
+    Left err -> do
+      putStrLn $ "❌ ERROR: " ++ show err
+      return False
+    Right result -> do
+      let success = result == expected
+      putStrLn $ "Output:"
+      putStrLn $ "  " ++ show result
+      putStrLn ""
+      if success
+        then putStrLn "✓ PASS"
+        else do
+          putStrLn "✗ FAIL"
+          putStrLn $ "\nExpected:"
+          putStrLn $ "  " ++ show expected
+      return success
+
+main :: IO ()
+main = do
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                       Gradient Feature Test Suite"
+  putStrLn $ replicate 80 '='
+
+  results <- sequenceA
+    [ testCase "Solid color (backwards compat)"
+        testSolid
+        "bg-blue-500"
+
+    , testCase "Two-color gradient"
+        testLinearGradient
+        "bg-gradient-to-r from-[#4E366C] to-white"
+
+    , testCase "Three-color gradient with via"
+        testLinearGradientVia
+        "bg-gradient-to-br from-purple-500 via-pink-500 to-white"
+
+    , testCase "Gradient with stop positions"
+        testGradientPositions
+        "bg-gradient-to-r from-[#4E366C] from-10% via-pink-500 via-30% to-white to-90%"
+
+    , testCase "Single color gradient (fade to transparent)"
+        testGradientFrom
+        "bg-gradient-to-r from-[#4E366C]"
+
+    , testCase "Two-color gradient with positions"
+        testLinearGradientPos
+        "bg-gradient-to-b from-blue-500 from-0% to-purple-500 to-100%"
+
+    , testCase "Gradient with hover transition"
+        testGradientTransition
+        "bg-blue-500 hover:bg-gradient-to-r hover:from-purple-500 hover:to-pink-500 hover:[transition:background-color,border-color,color,fill,stroke_300ms_linear_0ms]"
+
+    , testCase "Responsive gradients"
+        testResponsiveGradient
+        "bg-gray-500 sm:bg-gradient-to-r sm:from-blue-500 sm:to-purple-500"
+
+    , testCase "Direction: to-t"
+        testDirectionT
+        "bg-gradient-to-t from-blue-500 to-white"
+
+    , testCase "Direction: to-tr"
+        testDirectionTR
+        "bg-gradient-to-tr from-blue-500 to-white"
+
+    , testCase "Direction: to-bl"
+        testDirectionBL
+        "bg-gradient-to-bl from-blue-500 to-white"
+
+    , testCase "Direction: to-l"
+        testDirectionL
+        "bg-gradient-to-l from-blue-500 to-white"
+
+    , testCase "Direction: to-tl"
+        testDirectionTL
+        "bg-gradient-to-tl from-blue-500 to-white"
+    ]
+
+  putStrLn ""
+  putStrLn $ replicate 80 '='
+  putStrLn "                              SUMMARY"
+  putStrLn $ replicate 80 '='
+  let passed = length $ filter id results
+      total = length results
+  putStrLn $ "Tests passed: " ++ show passed ++ "/" ++ show total
+  putStrLn ""
+
+  if and results
+    then do
+      putStrLn "✓ ALL TESTS PASSED!"
+      putStrLn $ replicate 80 '='
+    else do
+      putStrLn "✗ SOME TESTS FAILED"
+      putStrLn $ replicate 80 '='

From 54c76a0b34a770d85d9c308700f74aa55541b04c Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Sun, 22 Feb 2026 18:31:36 -0500
Subject: [PATCH 21/29] test: update existing tests for GradientColor API

- Wrap all bgColor values with solidColor helper
- All test suites passing (transition, generate-html, comprehensive, gradient)
---
 test/ComprehensiveTest.hs |  8 +++----
 test/GenerateHTMLTest.hs  | 50 +++++++++++++++++++--------------------
 test/TransitionTest.hs    | 18 +++++++-------
 3 files changed, 38 insertions(+), 38 deletions(-)

diff --git a/test/ComprehensiveTest.hs b/test/ComprehensiveTest.hs
index 5e84f43..f2c68c4 100644
--- a/test/ComprehensiveTest.hs
+++ b/test/ComprehensiveTest.hs
@@ -28,13 +28,13 @@ testBoxBasics :: BoxConfig
 testBoxBasics = def
   & colStart .~~ 1
   & colSpan .~~ 6
-  & bgColor .~~ Blue C500
+  & bgColor .~~ solidColor (Blue C500)
   & bgOpacity .~~ 80
 
 -- Responsive properties with .|~
 testResponsive :: BoxConfig
 testResponsive = def
-  & bgColor .|~ [Gray C100, Gray C200, Gray C300, Gray C400, Gray C500, Gray C600]
+  & bgColor .|~ [solidColor (Gray C100), solidColor (Gray C200), solidColor (Gray C300), solidColor (Gray C400), solidColor (Gray C500), solidColor (Gray C600)]
 
 -- Padding with SetSides shorthand
 testPaddingSetSides :: BoxConfig
@@ -98,8 +98,8 @@ testPosition = def
 -- Combined complex test
 testComplex :: BoxConfig
 testComplex = def
-  & bgColor .~^ [ ("def", noTransition (Blue C600))
-                , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut)
+  & bgColor .~^ [ ("def", noTransition (solidColor (Blue C600)))
+                , ("hover", solidColor (Blue C400) `withTransition` Duration_300 `withTiming` Ease_InOut)
                 ]
   & padding . x .~~ TWSize 4
   & padding . y .~~ TWSize 2
diff --git a/test/GenerateHTMLTest.hs b/test/GenerateHTMLTest.hs
index 476533a..9793c18 100644
--- a/test/GenerateHTMLTest.hs
+++ b/test/GenerateHTMLTest.hs
@@ -42,9 +42,9 @@ tests =
 
 testBgAllStates :: BoxConfig
 testBgAllStates = def
-  & bgColor .~^ [ ("def", noTransition (Gray C500))
-                , ("hover", Blue C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
-                , ("focus", Green C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
+  & bgColor .~^ [ ("def", noTransition (solidColor (Gray C500)))
+                , ("hover", solidColor (Blue C500) `withTransition` Duration_300 `withTiming` Ease_InOut)
+                , ("focus", solidColor (Green C500) `withTransition` Duration_300 `withTiming` Ease_InOut)
                 ]
 
 testBorderAllStates :: BoxConfig
@@ -57,9 +57,9 @@ testBorderAllStates = def
 
 testCombined :: BoxConfig
 testCombined = def
-  & bgColor .~^ [ ("def", noTransition (Blue C600))
-                , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut)
-                , ("focus", Green C600 `withTransition` Duration_300 `withTiming` Ease_InOut)
+  & bgColor .~^ [ ("def", noTransition (solidColor (Blue C600)))
+                , ("hover", solidColor (Blue C400) `withTransition` Duration_300 `withTiming` Ease_InOut)
+                , ("focus", solidColor (Green C600) `withTransition` Duration_300 `withTiming` Ease_InOut)
                 ]
   & border . bWidth . allS .~~ B4
   & border . bColor . allS .~^ [ ("def", noTransition (Blue C800))
@@ -69,7 +69,7 @@ testCombined = def
 
 testResponsive :: BoxConfig
 testResponsive = def
-  & bgColor .|~ [ Gray C800, Red C600, Orange C600, Yellow C600, Green C600, Blue C600 ]
+  & bgColor .|~ [ solidColor (Gray C800), solidColor (Red C600), solidColor (Orange C600), solidColor (Yellow C600), solidColor (Green C600), solidColor (Blue C600) ]
 
 testShadow :: BoxConfig
 testShadow = def
@@ -79,8 +79,8 @@ testShadow = def
 
 testComplex :: BoxConfig
 testComplex = def
-  & bgColor .~^ [ ("def", noTransition (Blue C600))
-                , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut)
+  & bgColor .~^ [ ("def", noTransition (solidColor (Blue C600)))
+                , ("hover", solidColor (Blue C400) `withTransition` Duration_300 `withTiming` Ease_InOut)
                 ]
   & padding . x .~~ TWSize 4
   & padding . y .~~ TWSize 2
@@ -93,22 +93,22 @@ testComplex = def
 testComprehensiveResponsiveTransitions :: BoxConfig
 testComprehensiveResponsiveTransitions = def
   & bgColor .~^
-    [ ("def",   Red C600    `withTransition` Duration_500  `withTiming` Ease_Linear `withDelay` Delay_0)
-    , ("sm",    Orange C600 `withTransition` Duration_300  `withTiming` Ease_In     `withDelay` Delay_100)
-    , ("md",    Yellow C600 `withTransition` Duration_700  `withTiming` Ease_Out    `withDelay` Delay_150)
-    , ("lg",    Green C600  `withTransition` Duration_200  `withTiming` Ease_InOut  `withDelay` Delay_0)
-    , ("xl",    Blue C600   `withTransition` Duration_1000 `withTiming` Ease_Linear `withDelay` Delay_300)
-    , ("2xl",   Purple C600 `withTransition` Duration_500  `withTiming` Ease_InOut  `withDelay` Delay_75)
-    , ("hover", Pink C400   `withTransition` Duration_150  `withTiming` Ease_Out    `withDelay` Delay_0)
-    , ("focus", Cyan C400   `withTransition` Duration_300  `withTiming` Ease_InOut  `withDelay` Delay_200)
+    [ ("def",   solidColor (Red C600)    `withTransition` Duration_500  `withTiming` Ease_Linear `withDelay` Delay_0)
+    , ("sm",    solidColor (Orange C600) `withTransition` Duration_300  `withTiming` Ease_In     `withDelay` Delay_100)
+    , ("md",    solidColor (Yellow C600) `withTransition` Duration_700  `withTiming` Ease_Out    `withDelay` Delay_150)
+    , ("lg",    solidColor (Green C600)  `withTransition` Duration_200  `withTiming` Ease_InOut  `withDelay` Delay_0)
+    , ("xl",    solidColor (Blue C600)   `withTransition` Duration_1000 `withTiming` Ease_Linear `withDelay` Delay_300)
+    , ("2xl",   solidColor (Purple C600) `withTransition` Duration_500  `withTiming` Ease_InOut  `withDelay` Delay_75)
+    , ("hover", solidColor (Pink C400)   `withTransition` Duration_150  `withTiming` Ease_Out    `withDelay` Delay_0)
+    , ("focus", solidColor (Cyan C400)   `withTransition` Duration_300  `withTiming` Ease_InOut  `withDelay` Delay_200)
     ]
 
 testStackedTransitions :: BoxConfig
 testStackedTransitions = def
   & bgColor .~^
-    [ ("def",   Gray C800   `withTransition` Duration_300 `withTiming` Ease_Linear)
-    , ("sm",    Gray C700   `withTransition` Duration_300 `withTiming` Ease_In)
-    , ("hover", Green C500  `withTransition` Duration_200 `withTiming` Ease_Out)
+    [ ("def",   solidColor (Gray C800)   `withTransition` Duration_300 `withTiming` Ease_Linear)
+    , ("sm",    solidColor (Gray C700)   `withTransition` Duration_300 `withTiming` Ease_In)
+    , ("hover", solidColor (Green C500)  `withTransition` Duration_200 `withTiming` Ease_Out)
     ]
   & border . bWidth . allS .~~ B2
   & border . bColor . allS .~^
@@ -119,16 +119,16 @@ testStackedTransitions = def
 testDelayShowcase :: BoxConfig
 testDelayShowcase = def
   & bgColor .~^
-    [ ("def",   Blue C600 `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_0)
-    , ("hover", Blue C400 `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_500)
-    , ("focus", Blue C200 `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_1000)
+    [ ("def",   solidColor (Blue C600) `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_0)
+    , ("hover", solidColor (Blue C400) `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_500)
+    , ("focus", solidColor (Blue C200) `withTransition` Duration_300 `withTiming` Ease_InOut `withDelay` Delay_1000)
     ]
 
 testSpeedComparison :: BoxConfig
 testSpeedComparison = def
   & bgColor .~^
-    [ ("def",   Purple C600 `withTransition` Duration_75   `withTiming` Ease_Linear)
-    , ("hover", Purple C400 `withTransition` Duration_1000 `withTiming` Ease_Linear)
+    [ ("def",   solidColor (Purple C600) `withTransition` Duration_75   `withTiming` Ease_Linear)
+    , ("hover", solidColor (Purple C400) `withTransition` Duration_1000 `withTiming` Ease_Linear)
     ]
 
 generateHTML :: IO ()
diff --git a/test/TransitionTest.hs b/test/TransitionTest.hs
index 5fa9aa3..4894776 100644
--- a/test/TransitionTest.hs
+++ b/test/TransitionTest.hs
@@ -12,30 +12,30 @@ import qualified Data.Text as T
 -- Test 1: Backwards compatible - no transitions
 test1 :: BoxConfig
 test1 = def
-  & bgColor .~~ (Gray C500)
+  & bgColor .~~ solidColor (Gray C500)
   & colSpan .~~ 2
 
 -- Test 2: Using new (.~^) operator with builder pattern
 test2 :: BoxConfig
 test2 = def
-  & bgColor .~^ [ ("def", noTransition (Gray C500))
-                , ("hover", (Gray C300) `withTransition` Duration_300)
+  & bgColor .~^ [ ("def", noTransition (solidColor (Gray C500)))
+                , ("hover", solidColor (Gray C300) `withTransition` Duration_300)
                 ]
 
 -- Test 3: Builder pattern with chaining
 test3 :: BoxConfig
 test3 = def
-  & bgColor .~^ [ ("def", noTransition (Purple C600))
-                , ("hover", (Purple C300) `withTransition` Duration_300 `withTiming` Ease_InOut)
-                , ("focus", (Indigo C500) `withTransition` Duration_500 `withTiming` Ease_Out `withDelay` Delay_100)
+  & bgColor .~^ [ ("def", noTransition (solidColor (Purple C600)))
+                , ("hover", solidColor (Purple C300) `withTransition` Duration_300 `withTiming` Ease_InOut)
+                , ("focus", solidColor (Indigo C500) `withTransition` Duration_500 `withTiming` Ease_Out `withDelay` Delay_100)
                 ]
 
 -- Test 4: All-at-once style
 test4 :: BoxConfig
 test4 = def
-  & bgColor .~^ [ ("def", noTransition (Purple C600))
-                , ("sm", withTransitionAll (Indigo C500) Duration_300 Ease_InOut Delay_0)
-                , ("hover", (Purple C300) `withTransition` Duration_500)
+  & bgColor .~^ [ ("def", noTransition (solidColor (Purple C600)))
+                , ("sm", withTransitionAll (solidColor (Indigo C500)) Duration_300 Ease_InOut Delay_0)
+                , ("hover", solidColor (Purple C300) `withTransition` Duration_500)
                 ]
 
 testCase :: String -> BoxConfig -> T.Text -> IO Bool

From 848c0b13b9ab63ca997b280a13614597acbcec57 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Mon, 23 Feb 2026 10:03:12 -0500
Subject: [PATCH 22/29] feat: add ColorWithOpacity type for Tailwind /opacity
 syntax

Add support for colors with embedded opacity using Tailwind's
/opacity syntax (e.g., bg-blue-500/50, bg-[#1e40af]/87).

- Add ColorWithOpacity data type with color and opacity fields
- Add withOpacity helper function
- Add ShowTW instance rendering color/opacity format
- Add explicit module exports
---
 src/Classh/Color.hs | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/src/Classh/Color.hs b/src/Classh/Color.hs
index 8518180..d04b03c 100644
--- a/src/Classh/Color.hs
+++ b/src/Classh/Color.hs
@@ -17,7 +17,17 @@
 -- @
 --------------------------------------------------------------------------------
 
-module Classh.Color where
+module Classh.Color
+  ( -- * Color Types
+    Color(..)
+  , ColorNum(..)
+  , Hex(..)
+    -- * Color with Opacity
+  , ColorWithOpacity(..)
+  , withOpacity
+    -- * Hex Helper
+  , hex
+  ) where
 
 import Classh.Class.ShowTW
 import Classh.Internal.TShow
@@ -72,6 +82,31 @@ data Color
   | Color_Custom Hex
   deriving (Show, Eq)
 
+-- | Color with opacity (0-100).
+--
+-- Renders using Tailwind's @/opacity@ syntax, e.g., @bg-blue-500/50@.
+--
+-- === Example
+--
+-- @
+-- withOpacity (hex "1e40af") 50
+-- -- Renders as: [#1e40af]/50
+-- -- In bgColor context: bg-[#1e40af]/50
+-- @
+data ColorWithOpacity = ColorWithOpacity
+  { _cwo_color   :: Color
+  , _cwo_opacity :: Int  -- ^ Opacity value 0-100
+  } deriving (Show, Eq)
+
+-- | Create a color with opacity.
+--
+-- @
+-- withOpacity (Blue C500) 50  -- blue-500/50
+-- withOpacity (hex "1e40af") 87  -- [#1e40af]/87
+-- @
+withOpacity :: Color -> Int -> ColorWithOpacity
+withOpacity = ColorWithOpacity
+
 -- | Eg. see https://tailwindcss.com/docs/background-color
 data ColorNum
  = C50
@@ -100,3 +135,8 @@ instance ShowTW Color where
   showTW color = case T.words $ tshow color of
     c:(mag):[] -> (T.toLower c) <> "-" <> (T.drop 1 mag) -- T.words $ tshow color
     _ -> "ClasshSS: failed on input" <> (tshow color)
+
+-- | Renders as @color/opacity@, e.g., @blue-500/50@ or @[#1e40af]/87@
+instance ShowTW ColorWithOpacity where
+  showTW (ColorWithOpacity color opacity) =
+    showTW color <> "/" <> tshow opacity

From cd18dcfa0142e8e41d98dbcf65698b9f21d11e98 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Mon, 23 Feb 2026 10:05:28 -0500
Subject: [PATCH 23/29] feat: add opacity support to gradients and solid colors

Extend gradient API with opacity support for both solid colors
and gradient color stops.

Solid colors with opacity:
- Add SolidColorWithOpacity constructor to GradientColor
- Add solidColorOpacity helper for bg-[#hex]/opacity syntax

Gradient color stops with opacity:
- Add _stop_opacity field to ColorStop
- Add stopWithOpacity and stopAtWithOpacity helpers
- Update renderStop to include /opacity in output

This enables patterns like:
  bgColor .~~ solidColorOpacity (hex "4E366C") 87
  linearGradientPos To_BR (stopAtWithOpacity (hex "281C40") 90 0) ...
---
 src/Classh/Box/Gradient.hs | 73 +++++++++++++++++++++++++++++++-------
 1 file changed, 61 insertions(+), 12 deletions(-)

diff --git a/src/Classh/Box/Gradient.hs b/src/Classh/Box/Gradient.hs
index fc493b7..cc53463 100644
--- a/src/Classh/Box/Gradient.hs
+++ b/src/Classh/Box/Gradient.hs
@@ -46,9 +46,12 @@ module Classh.Box.Gradient
   , StopPosition(..)
     -- * Solid Color Helper
   , solidColor
+  , solidColorOpacity
     -- * Color Stop Helpers
   , stop
   , stopAt
+  , stopWithOpacity
+  , stopAtWithOpacity
     -- * Gradient Builders
   , linearGradient
   , linearGradientVia
@@ -84,16 +87,19 @@ data GradientDirection
 newtype StopPosition = StopPosition Int
   deriving (Show, Eq)
 
--- | A color stop with an optional position.
+-- | A color stop with optional opacity and position.
 --
 -- === Examples
 --
 -- @
--- stop White              -- Just the color
--- stopAt (Blue C500) 30   -- Color at 30%
+-- stop White                        -- Just the color
+-- stopAt (Blue C500) 30             -- Color at 30%
+-- stopWithOpacity (hex "181422") 90 -- Color with 90% opacity
+-- stopAtWithOpacity (hex "181422") 90 0  -- Opacity + position
 -- @
 data ColorStop = ColorStop
   { _stop_color    :: Color
+  , _stop_opacity  :: Maybe Int        -- ^ Opacity value 0-100 (optional)
   , _stop_position :: Maybe StopPosition
   } deriving (Show, Eq)
 
@@ -109,8 +115,17 @@ data GradientConfig = GradientConfig
 --
 -- This type replaces 'Color' in '_bgColor' and similar fields, allowing
 -- both simple colors and gradients to be used interchangeably.
+--
+-- === Examples
+--
+-- @
+-- SolidColor White                          -- bg-white
+-- SolidColorWithOpacity (withOpacity (hex "1e40af") 50)  -- bg-[#1e40af]/50
+-- GradientColor ...                         -- bg-gradient-to-r from-...
+-- @
 data GradientColor
   = SolidColor Color
+  | SolidColorWithOpacity ColorWithOpacity  -- ^ Solid color with opacity (e.g., @bg-[#hex]/50@)
   | GradientColor GradientConfig
   deriving (Show, Eq)
 
@@ -131,12 +146,13 @@ instance ShowTW GradientDirection where
 instance ShowTW StopPosition where
   showTW (StopPosition p) = tshow p <> "%"
 
--- | Helper to render a color stop with its position.
--- Generates output like @from-blue-500 from-10%@ or @via-pink-500 via-30%@
+-- | Helper to render a color stop with optional opacity and position.
+-- Generates output like @from-blue-500 from-10%@, @via-pink-500/50@, or @to-[#hex]/90 to-100%@
 renderStop :: T.Text -> ColorStop -> T.Text
-renderStop prefix (ColorStop color mpos) =
-  prefix <> "-" <> showTW color <>
-  maybe "" (\(StopPosition p) -> " " <> prefix <> "-" <> tshow p <> "%") mpos
+renderStop prefix (ColorStop color mOpacity mpos) =
+  let colorPart = showTW color <> maybe "" (\o -> "/" <> tshow o) mOpacity
+  in prefix <> "-" <> colorPart <>
+     maybe "" (\(StopPosition p) -> " " <> prefix <> "-" <> tshow p <> "%") mpos
 
 instance ShowTW GradientConfig where
   showTW (GradientConfig dir from mvia mto) =
@@ -147,6 +163,7 @@ instance ShowTW GradientConfig where
 
 instance ShowTW GradientColor where
   showTW (SolidColor color) = showTW color
+  showTW (SolidColorWithOpacity cwo) = showTW cwo  -- e.g., "[#1e40af]/50"
   showTW (GradientColor cfg) = showTW cfg
 
 --------------------------------------------------------------------------------
@@ -166,13 +183,29 @@ instance ShowTW GradientColor where
 solidColor :: Color -> GradientColor
 solidColor = SolidColor
 
--- | Create a color stop without a position.
+-- | Create a solid color with opacity.
+--
+-- Use this for semi-transparent backgrounds. Outputs Tailwind's @/opacity@ syntax.
+--
+-- === Example
 --
 -- @
--- stop White  -- ColorStop White Nothing
+-- bgColor .~~ solidColorOpacity (hex "221326") 87
+-- -- Generates: bg-[#221326]/87
+--
+-- bgColor .~~ solidColorOpacity (Blue C500) 50
+-- -- Generates: bg-blue-500/50
+-- @
+solidColorOpacity :: Color -> Int -> GradientColor
+solidColorOpacity c opacity = SolidColorWithOpacity (withOpacity c opacity)
+
+-- | Create a color stop without opacity or position.
+--
+-- @
+-- stop White  -- ColorStop White Nothing Nothing
 -- @
 stop :: Color -> ColorStop
-stop c = ColorStop c Nothing
+stop c = ColorStop c Nothing Nothing
 
 -- | Create a color stop at a specific position (0-100%).
 --
@@ -180,7 +213,23 @@ stop c = ColorStop c Nothing
 -- stopAt (Blue C500) 30  -- Blue at 30%
 -- @
 stopAt :: Color -> Int -> ColorStop
-stopAt c p = ColorStop c (Just $ StopPosition p)
+stopAt c p = ColorStop c Nothing (Just $ StopPosition p)
+
+-- | Create a color stop with opacity but no position.
+--
+-- @
+-- stopWithOpacity (hex "181422") 90  -- [#181422]/90
+-- @
+stopWithOpacity :: Color -> Int -> ColorStop
+stopWithOpacity c opacity = ColorStop c (Just opacity) Nothing
+
+-- | Create a color stop with both opacity and position.
+--
+-- @
+-- stopAtWithOpacity (hex "181422") 90 0  -- [#181422]/90 at 0%
+-- @
+stopAtWithOpacity :: Color -> Int -> Int -> ColorStop
+stopAtWithOpacity c opacity pos = ColorStop c (Just opacity) (Just $ StopPosition pos)
 
 -- | Create a two-color linear gradient.
 --

From 1b4418a81931035bef682cd88285dc02095cc605 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Mon, 23 Feb 2026 10:45:14 -0500
Subject: [PATCH 24/29] Refactor ColorWithOpacity as core color type

- Change _cwo_opacity from Int to Maybe Int (Nothing = fully opaque)
- Add 'color' smart constructor for Color -> ColorWithOpacity
- Update ShowTW instance to render opacity with Tailwind /n syntax
- This enables consistent opacity support across all color-using APIs
---
 src/Classh/Color.hs | 40 ++++++++++++++++++++++++++--------------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/src/Classh/Color.hs b/src/Classh/Color.hs
index d04b03c..6e69e07 100644
--- a/src/Classh/Color.hs
+++ b/src/Classh/Color.hs
@@ -24,6 +24,7 @@ module Classh.Color
   , Hex(..)
     -- * Color with Opacity
   , ColorWithOpacity(..)
+  , color
   , withOpacity
     -- * Hex Helper
   , hex
@@ -82,30 +83,40 @@ data Color
   | Color_Custom Hex
   deriving (Show, Eq)
 
--- | Color with opacity (0-100).
+-- | Color with optional opacity (0-100).
 --
--- Renders using Tailwind's @/opacity@ syntax, e.g., @bg-blue-500/50@.
+-- Renders using Tailwind's @/opacity@ syntax when opacity is present.
+-- When opacity is @Nothing@, renders as plain color (fully opaque).
 --
 -- === Example
 --
 -- @
--- withOpacity (hex "1e40af") 50
--- -- Renders as: [#1e40af]/50
--- -- In bgColor context: bg-[#1e40af]/50
+-- color (Blue C500)           -- blue-500 (no opacity suffix)
+-- withOpacity (Blue C500) 50  -- blue-500/50
+-- withOpacity (hex "1e40af") 87  -- [#1e40af]/87
 -- @
 data ColorWithOpacity = ColorWithOpacity
   { _cwo_color   :: Color
-  , _cwo_opacity :: Int  -- ^ Opacity value 0-100
+  , _cwo_opacity :: Maybe Int  -- ^ Nothing = fully opaque, Just n = n% opacity
   } deriving (Show, Eq)
 
--- | Create a color with opacity.
+-- | Create a color without explicit opacity (fully opaque).
+--
+-- @
+-- color (Blue C500)  -- blue-500
+-- color White        -- white
+-- @
+color :: Color -> ColorWithOpacity
+color c = ColorWithOpacity c Nothing
+
+-- | Create a color with explicit opacity (0-100).
 --
 -- @
 -- withOpacity (Blue C500) 50  -- blue-500/50
 -- withOpacity (hex "1e40af") 87  -- [#1e40af]/87
 -- @
 withOpacity :: Color -> Int -> ColorWithOpacity
-withOpacity = ColorWithOpacity
+withOpacity c o = ColorWithOpacity c (Just o)
 
 -- | Eg. see https://tailwindcss.com/docs/background-color
 data ColorNum
@@ -132,11 +143,12 @@ instance ShowTW Color where
   showTW Transparent = "transparent"
   showTW Black = "black"
   showTW White = "white"
-  showTW color = case T.words $ tshow color of
-    c:(mag):[] -> (T.toLower c) <> "-" <> (T.drop 1 mag) -- T.words $ tshow color
-    _ -> "ClasshSS: failed on input" <> (tshow color)
+  showTW col = case T.words $ tshow col of
+    c:(mag):[] -> (T.toLower c) <> "-" <> (T.drop 1 mag)
+    _ -> "ClasshSS: failed on input" <> (tshow col)
 
--- | Renders as @color/opacity@, e.g., @blue-500/50@ or @[#1e40af]/87@
+-- | Renders color with optional opacity suffix.
+-- @Nothing@ opacity renders plain color, @Just n@ renders @color/n@.
 instance ShowTW ColorWithOpacity where
-  showTW (ColorWithOpacity color opacity) =
-    showTW color <> "/" <> tshow opacity
+  showTW (ColorWithOpacity c Nothing) = showTW c
+  showTW (ColorWithOpacity c (Just o)) = showTW c <> "/" <> tshow o

From 896047f235948e0a0f8ddc9574fe91c07a4df33d Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Mon, 23 Feb 2026 10:45:37 -0500
Subject: [PATCH 25/29] Simplify Gradient types to use ColorWithOpacity

- Remove redundant SolidColorWithOpacity constructor from GradientColor
- SolidColor now takes ColorWithOpacity directly
- Simplify ColorStop to use ColorWithOpacity instead of separate opacity field
- Add solidColorOpacity and stopWithOpacity helper functions
- Update renderBgColorRaw for simplified GradientColor type
---
 src/Classh/Box.hs          |  2 +-
 src/Classh/Box/Gradient.hs | 44 ++++++++++++++++++--------------------
 2 files changed, 22 insertions(+), 24 deletions(-)

diff --git a/src/Classh/Box.hs b/src/Classh/Box.hs
index a0aae46..16341fa 100644
--- a/src/Classh/Box.hs
+++ b/src/Classh/Box.hs
@@ -556,7 +556,7 @@ instance Semigroup BoxConfig where
 -- | Render a GradientColor for bgColor without any prefix.
 -- Returns the raw class(es) that need prefixing.
 renderBgColorRaw :: GradientColor -> T.Text
-renderBgColorRaw (SolidColor color) = "bg-" <> showTW color
+renderBgColorRaw (SolidColor cwo) = "bg-" <> showTW cwo
 renderBgColorRaw (GradientColor cfg) = showTW cfg
 
 -- | Apply a prefix to each space-separated class.
diff --git a/src/Classh/Box/Gradient.hs b/src/Classh/Box/Gradient.hs
index cc53463..6c6f590 100644
--- a/src/Classh/Box/Gradient.hs
+++ b/src/Classh/Box/Gradient.hs
@@ -87,7 +87,9 @@ data GradientDirection
 newtype StopPosition = StopPosition Int
   deriving (Show, Eq)
 
--- | A color stop with optional opacity and position.
+-- | A color stop with optional position.
+--
+-- Uses 'ColorWithOpacity' which embeds opacity directly in the color.
 --
 -- === Examples
 --
@@ -98,8 +100,7 @@ newtype StopPosition = StopPosition Int
 -- stopAtWithOpacity (hex "181422") 90 0  -- Opacity + position
 -- @
 data ColorStop = ColorStop
-  { _stop_color    :: Color
-  , _stop_opacity  :: Maybe Int        -- ^ Opacity value 0-100 (optional)
+  { _stop_color    :: ColorWithOpacity  -- ^ Color with optional opacity
   , _stop_position :: Maybe StopPosition
   } deriving (Show, Eq)
 
@@ -119,19 +120,18 @@ data GradientConfig = GradientConfig
 -- === Examples
 --
 -- @
--- SolidColor White                          -- bg-white
--- SolidColorWithOpacity (withOpacity (hex "1e40af") 50)  -- bg-[#1e40af]/50
--- GradientColor ...                         -- bg-gradient-to-r from-...
+-- solidColor White                    -- bg-white
+-- solidColorOpacity (hex "1e40af") 50 -- bg-[#1e40af]/50
+-- linearGradient To_R ...             -- bg-gradient-to-r from-...
 -- @
 data GradientColor
-  = SolidColor Color
-  | SolidColorWithOpacity ColorWithOpacity  -- ^ Solid color with opacity (e.g., @bg-[#hex]/50@)
+  = SolidColor ColorWithOpacity  -- ^ Solid color (with optional opacity via ColorWithOpacity)
   | GradientColor GradientConfig
   deriving (Show, Eq)
 
 -- | Default is transparent solid color
 instance Default GradientColor where
-  def = SolidColor Transparent
+  def = SolidColor (color Transparent)
 
 instance ShowTW GradientDirection where
   showTW To_T  = "to-t"
@@ -146,13 +146,12 @@ instance ShowTW GradientDirection where
 instance ShowTW StopPosition where
   showTW (StopPosition p) = tshow p <> "%"
 
--- | Helper to render a color stop with optional opacity and position.
+-- | Helper to render a color stop with position.
 -- Generates output like @from-blue-500 from-10%@, @via-pink-500/50@, or @to-[#hex]/90 to-100%@
 renderStop :: T.Text -> ColorStop -> T.Text
-renderStop prefix (ColorStop color mOpacity mpos) =
-  let colorPart = showTW color <> maybe "" (\o -> "/" <> tshow o) mOpacity
-  in prefix <> "-" <> colorPart <>
-     maybe "" (\(StopPosition p) -> " " <> prefix <> "-" <> tshow p <> "%") mpos
+renderStop prefix (ColorStop cwo mpos) =
+  prefix <> "-" <> showTW cwo <>
+  maybe "" (\(StopPosition p) -> " " <> prefix <> "-" <> tshow p <> "%") mpos
 
 instance ShowTW GradientConfig where
   showTW (GradientConfig dir from mvia mto) =
@@ -162,8 +161,7 @@ instance ShowTW GradientConfig where
     maybe "" (\t -> " " <> renderStop "to" t) mto
 
 instance ShowTW GradientColor where
-  showTW (SolidColor color) = showTW color
-  showTW (SolidColorWithOpacity cwo) = showTW cwo  -- e.g., "[#1e40af]/50"
+  showTW (SolidColor cwo) = showTW cwo
   showTW (GradientColor cfg) = showTW cfg
 
 --------------------------------------------------------------------------------
@@ -181,7 +179,7 @@ instance ShowTW GradientColor where
 -- bgColor .~~ solidColor (Blue C500)
 -- @
 solidColor :: Color -> GradientColor
-solidColor = SolidColor
+solidColor c = SolidColor (color c)
 
 -- | Create a solid color with opacity.
 --
@@ -197,15 +195,15 @@ solidColor = SolidColor
 -- -- Generates: bg-blue-500/50
 -- @
 solidColorOpacity :: Color -> Int -> GradientColor
-solidColorOpacity c opacity = SolidColorWithOpacity (withOpacity c opacity)
+solidColorOpacity c opacity = SolidColor (withOpacity c opacity)
 
 -- | Create a color stop without opacity or position.
 --
 -- @
--- stop White  -- ColorStop White Nothing Nothing
+-- stop White  -- ColorStop (color White) Nothing
 -- @
 stop :: Color -> ColorStop
-stop c = ColorStop c Nothing Nothing
+stop c = ColorStop (color c) Nothing
 
 -- | Create a color stop at a specific position (0-100%).
 --
@@ -213,7 +211,7 @@ stop c = ColorStop c Nothing Nothing
 -- stopAt (Blue C500) 30  -- Blue at 30%
 -- @
 stopAt :: Color -> Int -> ColorStop
-stopAt c p = ColorStop c Nothing (Just $ StopPosition p)
+stopAt c p = ColorStop (color c) (Just $ StopPosition p)
 
 -- | Create a color stop with opacity but no position.
 --
@@ -221,7 +219,7 @@ stopAt c p = ColorStop c Nothing (Just $ StopPosition p)
 -- stopWithOpacity (hex "181422") 90  -- [#181422]/90
 -- @
 stopWithOpacity :: Color -> Int -> ColorStop
-stopWithOpacity c opacity = ColorStop c (Just opacity) Nothing
+stopWithOpacity c opacity = ColorStop (withOpacity c opacity) Nothing
 
 -- | Create a color stop with both opacity and position.
 --
@@ -229,7 +227,7 @@ stopWithOpacity c opacity = ColorStop c (Just opacity) Nothing
 -- stopAtWithOpacity (hex "181422") 90 0  -- [#181422]/90 at 0%
 -- @
 stopAtWithOpacity :: Color -> Int -> Int -> ColorStop
-stopAtWithOpacity c opacity pos = ColorStop c (Just opacity) (Just $ StopPosition pos)
+stopAtWithOpacity c opacity pos = ColorStop (withOpacity c opacity) (Just $ StopPosition pos)
 
 -- | Create a two-color linear gradient.
 --

From 952d8a5a15967337204e3ee95570ed265ec31055 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Mon, 23 Feb 2026 10:45:58 -0500
Subject: [PATCH 26/29] Propagate ColorWithOpacity to border, text, and ring

- Update BorderColorConfig fields to use ColorWithOpacity
- Update SetSides instance for border color
- Update RingConfig ringColor to use ColorWithOpacity
- Update TextConfigTW text_color to use ColorWithOpacity
- Update TextDecorationConfigTW textDec_color to use ColorWithOpacity
- Update Shorthand bc* lenses for new type signatures
---
 src/Classh/Box/Border/Color.hs | 12 ++++++------
 src/Classh/Box/Ring.hs         |  2 +-
 src/Classh/Shorthand.hs        |  2 +-
 src/Classh/Text.hs             |  4 ++--
 src/Classh/Text/Decoration.hs  |  2 +-
 5 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/src/Classh/Box/Border/Color.hs b/src/Classh/Box/Border/Color.hs
index 4363c68..a749e9f 100644
--- a/src/Classh/Box/Border/Color.hs
+++ b/src/Classh/Box/Border/Color.hs
@@ -23,13 +23,13 @@ import Control.Lens (lens, makeLenses)
 -- > -- With transitions:
 -- > elClass "div" $(classh' [ bc_t .~^ [("def", Black), ("hover", Red `withTransition` Duration_300)] ])
 data BorderColorSides = BorderColorSides
-  { _borderColor_l :: WhenTW (WithTransition Color)
+  { _borderColor_l :: WhenTW (WithTransition ColorWithOpacity)
   -- ^ border-l-'Color' ... see https://tailwindcss.com/docs/border-color
-  , _borderColor_r :: WhenTW (WithTransition Color)
+  , _borderColor_r :: WhenTW (WithTransition ColorWithOpacity)
   -- ^ border-r-'Color' ... see https://tailwindcss.com/docs/border-color
-  , _borderColor_t :: WhenTW (WithTransition Color)
+  , _borderColor_t :: WhenTW (WithTransition ColorWithOpacity)
   -- ^ border-t-'Color' ... see https://tailwindcss.com/docs/border-color
-  , _borderColor_b :: WhenTW (WithTransition Color)
+  , _borderColor_b :: WhenTW (WithTransition ColorWithOpacity)
   -- ^ border-b-'Color' ... see https://tailwindcss.com/docs/border-color
   } deriving Show
 
@@ -48,8 +48,8 @@ instance ShowTW BorderColorSides where
 makeLenses ''BorderColorSides
 
 -- | Like border-'Color', eg border-white
--- Now uses WithTransition Color so .~~ will auto-wrap, and .~^ allows transitions
-instance SetSides BorderColorSides (WithTransition Color) where
+-- Now uses WithTransition ColorWithOpacity so .~~ will auto-wrap, and .~^ allows transitions
+instance SetSides BorderColorSides (WithTransition ColorWithOpacity) where
   l = borderColor_l
   r = borderColor_r
   t = borderColor_t
diff --git a/src/Classh/Box/Ring.hs b/src/Classh/Box/Ring.hs
index 188edec..d32e90a 100644
--- a/src/Classh/Box/Ring.hs
+++ b/src/Classh/Box/Ring.hs
@@ -54,7 +54,7 @@ data RingWidth
 -- | Ring configuration (transitionable)
 data RingConfig = RingConfig
   { _ringWidth :: WhenTW (WithTransition RingWidth)
-  , _ringColor :: WhenTW (WithTransition Color)
+  , _ringColor :: WhenTW (WithTransition ColorWithOpacity)
   , _ringOpacity :: WhenTW (WithTransition Int)  -- 0-100
   } deriving Show
 
diff --git a/src/Classh/Shorthand.hs b/src/Classh/Shorthand.hs
index 6aba3c1..0a5dd69 100644
--- a/src/Classh/Shorthand.hs
+++ b/src/Classh/Shorthand.hs
@@ -60,7 +60,7 @@ bw_x = border . bWidth . x
 bw = border . bWidth . allS
 
 -- | Set border color side(s)
-bc_r, bc_l, bc_t, bc_b, bc_y, bc_x, bc :: Setter BoxConfig (WhenTW (WithTransition Color))
+bc_r, bc_l, bc_t, bc_b, bc_y, bc_x, bc :: Setter BoxConfig (WhenTW (WithTransition ColorWithOpacity))
 bc_r = border . bColor . r 
 bc_l = border . bColor . l
 bc_t = border . bColor . t
diff --git a/src/Classh/Text.hs b/src/Classh/Text.hs
index 735820c..1495918 100644
--- a/src/Classh/Text.hs
+++ b/src/Classh/Text.hs
@@ -368,8 +368,8 @@ data TextConfigTW = TextConfigTW
     -- ^ Font weight (Thin through Black_TextWeight). Default: empty (browser default)
   , _text_font :: WhenTW Font
     -- ^ Font family (Sans, Serif, Mono, or Font_Custom \"Name\"). Default: empty (browser default)
-  , _text_color :: WhenTW Color
-    -- ^ Text color. Default: empty (browser default, usually black)
+  , _text_color :: WhenTW ColorWithOpacity
+    -- ^ Text color with optional opacity. Default: empty (browser default, usually black)
   , _text_decoration :: TextDecorationTW
     -- ^ Text decoration (underline, overline, strikethrough, color, style, thickness, offset)
   , _text_style :: WhenTW FontStyle
diff --git a/src/Classh/Text/Decoration.hs b/src/Classh/Text/Decoration.hs
index e690a19..34096d8 100644
--- a/src/Classh/Text/Decoration.hs
+++ b/src/Classh/Text/Decoration.hs
@@ -71,7 +71,7 @@ instance ShowTW TextDecorationTW where
 data TextDecorationTW = TextDecorationTW
   { _textDec_line :: WhenTW TextDecLineType
   -- ^ https://tailwindcss.com/docs/text-decoration
-  , _textDec_color :: WhenTW Color
+  , _textDec_color :: WhenTW ColorWithOpacity
   -- ^ https://tailwindcss.com/docs/text-decoration-color
   , _textDec_style :: WhenTW TextDecStyle
   -- ^ https://tailwindcss.com/docs/text-decoration-style

From b30ced0bd74f24ff7a0b7a688a89bca1b0ea603a Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Mon, 23 Feb 2026 10:46:17 -0500
Subject: [PATCH 27/29] Add opacity tests and update tests for ColorWithOpacity
 API

- Add testSolidColorOpacity: solid color with /87 opacity
- Add testStopWithOpacity: gradient stop with opacity
- Add testStopAtWithOpacity: positioned stop with opacity
- Add testGradientMixedOpacity: mixed opacity and non-opacity stops
- Wrap bare Color values with 'color' helper in ComprehensiveTest
- Wrap bare Color values with 'color' helper in GenerateHTMLTest
---
 test/ComprehensiveTest.hs |  6 +++---
 test/GenerateHTMLTest.hs  | 16 ++++++++--------
 test/GradientTest.hs      | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/test/ComprehensiveTest.hs b/test/ComprehensiveTest.hs
index f2c68c4..5dafb26 100644
--- a/test/ComprehensiveTest.hs
+++ b/test/ComprehensiveTest.hs
@@ -61,14 +61,14 @@ testMargin = def
 testBorder :: BoxConfig
 testBorder = def
   & border . bWidth . b .~~ B2
-  & border . bColor . allS .~~ Red C500
+  & border . bColor . allS .~~ color (Red C500)
   & border . radius . borderRadius_tr .~~ R_Lg
 
 -- Border with transitions
 testBorderTransitions :: BoxConfig
 testBorderTransitions = def
-  & border . bColor . allS .~^ [ ("def", noTransition (Blue C500))
-                                , ("hover", Red C500 `withTransition` Duration_200)
+  & border . bColor . allS .~^ [ ("def", noTransition (color (Blue C500)))
+                                , ("hover", color (Red C500) `withTransition` Duration_200)
                                 ]
 
 -- Shadow tests
diff --git a/test/GenerateHTMLTest.hs b/test/GenerateHTMLTest.hs
index 9793c18..4442b9a 100644
--- a/test/GenerateHTMLTest.hs
+++ b/test/GenerateHTMLTest.hs
@@ -50,9 +50,9 @@ testBgAllStates = def
 testBorderAllStates :: BoxConfig
 testBorderAllStates = def
   & border . bWidth . allS .~~ B4
-  & border . bColor . allS .~^ [ ("def", noTransition (Gray C400))
-                                , ("hover", Purple C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
-                                , ("focus", Yellow C500 `withTransition` Duration_300 `withTiming` Ease_InOut)
+  & border . bColor . allS .~^ [ ("def", noTransition (color (Gray C400)))
+                                , ("hover", color (Purple C500) `withTransition` Duration_300 `withTiming` Ease_InOut)
+                                , ("focus", color (Yellow C500) `withTransition` Duration_300 `withTiming` Ease_InOut)
                                 ]
 
 testCombined :: BoxConfig
@@ -62,9 +62,9 @@ testCombined = def
                 , ("focus", solidColor (Green C600) `withTransition` Duration_300 `withTiming` Ease_InOut)
                 ]
   & border . bWidth . allS .~~ B4
-  & border . bColor . allS .~^ [ ("def", noTransition (Blue C800))
-                                , ("hover", Blue C600 `withTransition` Duration_300 `withTiming` Ease_InOut)
-                                , ("focus", Green C800 `withTransition` Duration_300 `withTiming` Ease_InOut)
+  & border . bColor . allS .~^ [ ("def", noTransition (color (Blue C800)))
+                                , ("hover", color (Blue C600) `withTransition` Duration_300 `withTiming` Ease_InOut)
+                                , ("focus", color (Green C800) `withTransition` Duration_300 `withTiming` Ease_InOut)
                                 ]
 
 testResponsive :: BoxConfig
@@ -112,8 +112,8 @@ testStackedTransitions = def
     ]
   & border . bWidth . allS .~~ B2
   & border . bColor . allS .~^
-    [ ("def",   Gray C600   `withTransition` Duration_300)
-    , ("hover", Green C400  `withTransition` Duration_200)
+    [ ("def",   color (Gray C600)   `withTransition` Duration_300)
+    , ("hover", color (Green C400)  `withTransition` Duration_200)
     ]
 
 testDelayShowcase :: BoxConfig
diff --git a/test/GradientTest.hs b/test/GradientTest.hs
index f5bd7cc..db72335 100644
--- a/test/GradientTest.hs
+++ b/test/GradientTest.hs
@@ -74,6 +74,28 @@ testDirectionL = def & bgColor .~~ linearGradient To_L (Blue C500) White
 testDirectionTL :: BoxConfig
 testDirectionTL = def & bgColor .~~ linearGradient To_TL (Blue C500) White
 
+-- Test 10: Solid color with opacity
+testSolidColorOpacity :: BoxConfig
+testSolidColorOpacity = def
+  & bgColor .~~ solidColorOpacity (hex "221326") 87
+
+-- Test 11: Gradient stop with opacity
+testStopWithOpacity :: BoxConfig
+testStopWithOpacity = def
+  & bgColor .~~ linearGradientPos To_BR
+      (stopAtWithOpacity (hex "181422") 90 0)
+      (stopAt (hex "281C40") 100)
+
+-- Test 12: Named color with opacity
+testNamedColorOpacity :: BoxConfig
+testNamedColorOpacity = def
+  & bgColor .~~ solidColorOpacity (Blue C500) 50
+
+-- Test 13: color helper (no opacity suffix)
+testColorHelper :: BoxConfig
+testColorHelper = def
+  & bgColor .~~ solidColor White
+
 testCase :: String -> BoxConfig -> T.Text -> IO Bool
 testCase name cfg expected = do
   putStrLn $ "\n" ++ replicate 80 '-'
@@ -155,6 +177,22 @@ main = do
     , testCase "Direction: to-tl"
         testDirectionTL
         "bg-gradient-to-tl from-blue-500 to-white"
+
+    , testCase "Solid color with opacity (hex)"
+        testSolidColorOpacity
+        "bg-[#221326]/87"
+
+    , testCase "Gradient stop with opacity"
+        testStopWithOpacity
+        "bg-gradient-to-br from-[#181422]/90 from-0% to-[#281C40] to-100%"
+
+    , testCase "Named color with opacity"
+        testNamedColorOpacity
+        "bg-blue-500/50"
+
+    , testCase "color helper (no opacity suffix)"
+        testColorHelper
+        "bg-white"
     ]
 
   putStrLn ""

From 92d29d4d9b472c24f4231a205c6bbb6521665e7c Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Thu, 19 Mar 2026 14:43:54 -0400
Subject: [PATCH 28/29] Change BoxMargin fields from TWSize to TWSizeOrFraction

Enables type-safe mx/ml/mr .~~ TWSize_Auto instead of custom .~ "mx-auto".
Margin shorthands (mt, mb, ml, mr, mx, my, m) now accept TWSizeOrFraction,
which includes Auto, Full, Fraction etc. in addition to numeric TWSize values.
Call sites use twSize' N instead of TWSize N for margin values.
---
 src/Classh/Box/Margin.hs  | 12 +++++++-----
 src/Classh/Shorthand.hs   |  2 +-
 test/ComprehensiveTest.hs |  6 +++---
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/src/Classh/Box/Margin.hs b/src/Classh/Box/Margin.hs
index 8acf8cd..77f4aab 100644
--- a/src/Classh/Box/Margin.hs
+++ b/src/Classh/Box/Margin.hs
@@ -68,14 +68,16 @@ instance ShowTW BoxMargin where
 
 -- | Type representing '_margin' field of 'BoxConfig' (transitionable).
 -- | based on https://tailwindcss.com/docs/margin
+-- | Uses 'TWSizeOrFraction' instead of 'TWSize' to support 'TWSize_Auto'
+-- | (e.g. @mx .~~ TWSize_Auto@ generates @mx-auto@)
 data BoxMargin = BoxMargin
-  { _marginL :: WhenTW (WithTransition TWSize)
+  { _marginL :: WhenTW (WithTransition TWSizeOrFraction)
   -- ^ see shorthand: @ml@
-  , _marginR :: WhenTW (WithTransition TWSize)
+  , _marginR :: WhenTW (WithTransition TWSizeOrFraction)
   -- ^ see shorthand: 'mr'
-  , _marginT :: WhenTW (WithTransition TWSize)
+  , _marginT :: WhenTW (WithTransition TWSizeOrFraction)
   -- ^ see shorthand: 'mt'
-  , _marginB :: WhenTW (WithTransition TWSize)
+  , _marginB :: WhenTW (WithTransition TWSizeOrFraction)
   -- ^ see shorthand: 'mb'
   } deriving Show
 
@@ -92,7 +94,7 @@ instance Semigroup BoxMargin where
 -- | This is technically an illegal lens however if you ran 2 setters which overlap so that a /= b
 -- | where a and b are the fields associated with respective separate fields, then classh' will
 -- | most likely catch the error. Additionally, there is a lens way to access any field anyways
-instance SetSides BoxMargin (WithTransition TWSize) where
+instance SetSides BoxMargin (WithTransition TWSizeOrFraction) where
   l = marginL
   r = marginR
   b = marginB
diff --git a/src/Classh/Shorthand.hs b/src/Classh/Shorthand.hs
index 0a5dd69..b226122 100644
--- a/src/Classh/Shorthand.hs
+++ b/src/Classh/Shorthand.hs
@@ -100,7 +100,7 @@ minH :: Setter BoxConfig (WhenTW (WithTransition DimensionConstraint))
 minH = sizingBand . minSize . heightC
 
 -- | Set margin on a given side(s)
-mt, ml, mr, mb, mx, my, m :: Setter BoxConfig (WhenTW (WithTransition TWSize))
+mt, ml, mr, mb, mx, my, m :: Setter BoxConfig (WhenTW (WithTransition TWSizeOrFraction))
 mt = margin . t
 mb = margin . b
 ml = margin . l
diff --git a/test/ComprehensiveTest.hs b/test/ComprehensiveTest.hs
index 5dafb26..576d5b1 100644
--- a/test/ComprehensiveTest.hs
+++ b/test/ComprehensiveTest.hs
@@ -53,9 +53,9 @@ testPaddingTransitions = def
 -- Margin tests
 testMargin :: BoxConfig
 testMargin = def
-  & margin . marginL .~~ TWSize 2
-  & margin . marginR .~~ TWSize 2
-  & margin . y .~~ TWSize 4
+  & margin . marginL .~~ twSize' 2
+  & margin . marginR .~~ twSize' 2
+  & margin . y .~~ twSize' 4
 
 -- Border tests
 testBorder :: BoxConfig

From bb57395ec509a54bf448aeeb3684379c55781ba4 Mon Sep 17 00:00:00 2001
From: lazyLambda <galen.sprout@gmail.com>
Date: Tue, 24 Mar 2026 19:50:30 -0400
Subject: [PATCH 29/29] henforcer compliance: fix all 65 modules

Add henforcer.toml with max strictness config. Fix open unaliased
imports across all modules by adding explicit import lists or aliases.
Replace duplicate 'as X' re-export aliases with unique module aliases
and update export lists accordingly. Add missing module header fields
(copyright, license, maintainer) where absent.
---
 ClasshSS.cabal                               |  3 +
 henforcer.toml                               | 15 ++++
 shell.nix                                    | 14 ++--
 src/Classh.hs                                | 62 ++++++++++-------
 src/Classh/Box.hs                            | 60 +++++++++-------
 src/Classh/Box/Border.hs                     | 28 +++++---
 src/Classh/Box/Border/Color.hs               | 21 ++++--
 src/Classh/Box/Border/Radius.hs              | 25 ++++---
 src/Classh/Box/Border/Style.hs               | 13 +++-
 src/Classh/Box/Border/Width.hs               | 25 ++++---
 src/Classh/Box/DivInt.hs                     |  7 +-
 src/Classh/Box/Gradient.hs                   |  9 +--
 src/Classh/Box/Margin.hs                     | 13 ++--
 src/Classh/Box/Outline.hs                    |  7 +-
 src/Classh/Box/Padding.hs                    | 15 ++--
 src/Classh/Box/Placement.hs                  | 12 ++--
 src/Classh/Box/Placement/Align.hs            |  5 +-
 src/Classh/Box/Placement/Justify.hs          |  5 +-
 src/Classh/Box/Ring.hs                       | 15 ++--
 src/Classh/Box/Shadow.hs                     |  7 +-
 src/Classh/Box/Sizing/BoxSizing.hs           | 13 ++--
 src/Classh/Box/Sizing/BoxSizingConstraint.hs |  7 +-
 src/Classh/Box/Sizing/DimensionConstraint.hs |  7 +-
 src/Classh/Box/SizingBand.hs                 | 24 ++++---
 src/Classh/Box/TWSize.hs                     | 18 ++---
 src/Classh/Box/Transform.hs                  | 15 ++--
 src/Classh/Box/Transition.hs                 | 11 +--
 src/Classh/Class/CompileStyle.hs             |  7 ++
 src/Classh/Class/HasCSSSize.hs               |  9 ++-
 src/Classh/Class/HasCustom.hs                |  9 ++-
 src/Classh/Class/IsCSS.hs                    |  7 ++
 src/Classh/Class/SetSides.hs                 | 11 ++-
 src/Classh/Class/ShowTW.hs                   |  7 ++
 src/Classh/Color.hs                          |  7 +-
 src/Classh/Cursor.hs                         |  7 +-
 src/Classh/Grid.hs                           |  5 +-
 src/Classh/Internal/CSSSize.hs               |  5 +-
 src/Classh/Internal/Chain.hs                 |  7 ++
 src/Classh/Internal/TShow.hs                 |  7 ++
 src/Classh/Internal/TWNum.hs                 | 19 +++---
 src/Classh/Internal/Utils.hs                 |  9 ++-
 src/Classh/Responsive/WhenTW.hs              |  5 +-
 src/Classh/Responsive/ZipScreens.hs          |  5 +-
 src/Classh/Setters.hs                        |  7 +-
 src/Classh/Shorthand.hs                      |  9 +--
 src/Classh/Text.hs                           | 41 ++++++-----
 src/Classh/Text/Decoration.hs                | 25 ++++---
 src/Classh/Text/Decoration/LineType.hs       |  7 +-
 src/Classh/Text/Decoration/Offset.hs         | 11 +--
 src/Classh/Text/Decoration/Style.hs          |  7 +-
 src/Classh/Text/Decoration/Thickness.hs      | 11 +--
 src/Classh/Text/Font.hs                      |  7 +-
 src/Classh/Text/FontStyle.hs                 | 13 +++-
 src/Classh/Text/Size.hs                      |  5 +-
 src/Classh/Text/Weight.hs                    |  7 +-
 src/Classh/TextPosition.hs                   | 72 ++++++++++++--------
 src/Classh/TextPosition/Clamp.hs             | 11 ++-
 src/Classh/TextPosition/Content.hs           | 11 ++-
 src/Classh/TextPosition/Hyphen.hs            | 11 ++-
 src/Classh/TextPosition/Lead.hs              | 11 ++-
 src/Classh/TextPosition/TAlign.hs            | 11 ++-
 src/Classh/TextPosition/TOverflow.hs         | 11 ++-
 src/Classh/TextPosition/Track.hs             | 11 ++-
 src/Classh/TextPosition/VAlign.hs            | 11 ++-
 src/Classh/TextPosition/WhiteSpace.hs        | 11 ++-
 src/Classh/TextPosition/WordBreak.hs         | 11 ++-
 src/Classh/TextPosition/Wrap.hs              | 11 ++-
 src/Classh/WithTransition.hs                 |  9 +--
 68 files changed, 613 insertions(+), 321 deletions(-)
 create mode 100644 henforcer.toml

diff --git a/ClasshSS.cabal b/ClasshSS.cabal
index 4bf395d..dbb5583 100644
--- a/ClasshSS.cabal
+++ b/ClasshSS.cabal
@@ -116,6 +116,9 @@ library
                       -->= 1.2.5 && < 1.3
     hs-source-dirs:   src
     ghc-options: -Wall -Werror -O -threaded -fno-show-valid-hole-fits
+    if impl(ghc >= 9.4)
+      build-depends: henforcer
+      ghc-options: -fplugin Henforcer
     default-language: Haskell2010
 
 test-suite transition-test
diff --git a/henforcer.toml b/henforcer.toml
new file mode 100644
index 0000000..bff5f7b
--- /dev/null
+++ b/henforcer.toml
@@ -0,0 +1,15 @@
+[forAnyModule]
+# 1 to account for the implicit Prelude import which is always open/unaliased
+allowedOpenUnaliasedImports = 1
+moduleHeaderCopyrightMustExistNonEmpty = true
+moduleHeaderDescriptionMustExistNonEmpty = true
+moduleHeaderLicenseMustExistNonEmpty = true
+moduleHeaderMaintainerMustExistNonEmpty = true
+allowedAliasUniqueness = { allAliasesUniqueExcept = [] }
+
+[[forSpecificModule]]
+moduleMatchRule = { matches = "Paths_ClasshSS" }
+moduleHeaderCopyrightMustExistNonEmpty = false
+moduleHeaderDescriptionMustExistNonEmpty = false
+moduleHeaderLicenseMustExistNonEmpty = false
+moduleHeaderMaintainerMustExistNonEmpty = false
diff --git a/shell.nix b/shell.nix
index b3f3b8e..bfcbc7d 100644
--- a/shell.nix
+++ b/shell.nix
@@ -5,14 +5,16 @@ let
   haskellPackages = if compiler == "default"
                        then pkgs.haskellPackages
                        else pkgs.haskell.packages.${compiler};
+  hpkgs = haskellPackages.override {
+    overrides = self: super: {
+      henforcer = self.callHackage "henforcer" "1.0.0.1" {};
+    };
+  };
   variant = if doBenchmark then pkgs.haskell.lib.doBenchmark else pkgs.lib.id;
-  wikiScraper = import ./default.nix;
-  drv = variant (haskellPackages.callPackage wikiScraper {}); 
+  classhSS = import ./default.nix;
+  drv = variant (hpkgs.callPackage classhSS {});
 in
 pkgs.mkShell {
   buildInputs = [ pkgs.cabal-install ];
   inputsFrom = [ (if pkgs.lib.inNixShell then drv.env else drv) ];
-} 
-
-
-
+}
diff --git a/src/Classh.hs b/src/Classh.hs
index 62c008f..ab50473 100644
--- a/src/Classh.hs
+++ b/src/Classh.hs
@@ -7,6 +7,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh
+--  Description :  Type-safe Tailwind CSS class generation via Template Haskell
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -331,7 +332,22 @@ module Classh
   , classhV'
   , boxCSS
   -- * Re-Exports
-  , module X
+  , module Box
+  , module Text
+  , module TextPosition
+  , module Grid
+  , module ZipScreens
+  , module Setters
+  , module Shorthand
+  , module ShowTW
+  , module CompileStyle
+  , module HasCSSSize
+  , module HasCustom
+  , module IsCSS
+  , module SetSides
+  , module Chain
+  , module TShow
+  , module Utils
   -- * Extend
   , alsoF
   , also
@@ -346,31 +362,25 @@ module Classh
   , CompiledClassh
   ) where
 
--- import Classh.Border
--- import Classh.ShowTW
--- import Classh.WhenTW
-import Classh.Box as X
-import Classh.Text as X
-import Classh.TextPosition as X
-import Classh.Grid as X
---import Classh.Cursor as X
---import Classh.Color as X
---import Classh.Responsive.WhenTW as X
-import Classh.Responsive.ZipScreens as X
-import Classh.Setters as X
-import Classh.Shorthand as X
-import Classh.Class.ShowTW as X
-import Classh.Class.CompileStyle as X
-import Classh.Class.HasCSSSize as X
-import Classh.Class.HasCustom as X
-import Classh.Class.IsCSS as X
-import Classh.Class.SetSides as X
-import Classh.Internal.Chain as X
-import Classh.Internal.TShow as X
-import Classh.Internal.Utils as X
-
-import Data.Default
-import "template-haskell" Language.Haskell.TH
+import Classh.Box as Box
+import Classh.Text as Text
+import Classh.TextPosition as TextPosition
+import Classh.Grid as Grid
+import Classh.Responsive.ZipScreens as ZipScreens
+import Classh.Setters as Setters
+import Classh.Shorthand as Shorthand
+import Classh.Class.ShowTW as ShowTW
+import Classh.Class.CompileStyle as CompileStyle
+import Classh.Class.HasCSSSize as HasCSSSize
+import Classh.Class.HasCustom as HasCustom
+import Classh.Class.IsCSS as IsCSS
+import Classh.Class.SetSides as SetSides
+import Classh.Internal.Chain as Chain
+import Classh.Internal.TShow as TShow
+import Classh.Internal.Utils as Utils
+
+import Data.Default (Default(..))
+import "template-haskell" Language.Haskell.TH as TH
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/Box.hs b/src/Classh/Box.hs
index 16341fa..234e8ea 100644
--- a/src/Classh/Box.hs
+++ b/src/Classh/Box.hs
@@ -4,6 +4,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box
+--  Description :  Box model configuration type and lenses
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -304,7 +305,21 @@ module Classh.Box
   (
     -- * Core Config Type 
     BoxConfig(..)
-  , module X
+  , module TWNum
+  , module WhenTW
+  , module Color
+  , module Gradient
+  , module Cursor
+  , module TWSize
+  , module Padding
+  , module Margin
+  , module SizingBand
+  , module Placement
+  , module Border
+  , module Shadow
+  , module Transition
+  , module Transform
+  , module WT
   -- * Auto Generated Lenses
   , colStart
   , colSpan
@@ -321,31 +336,30 @@ module Classh.Box
   , box_custom
   ) where
 
--- Our goto module
-import Classh.Class.HasCustom
-import Classh.Class.ShowTW
-import Classh.Class.CompileStyle
-import Classh.Internal.Chain
-import Classh.Internal.TShow
+import Classh.Class.HasCustom as HasCustom
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.CompileStyle as CompileStyle
+import Classh.Internal.Chain ((<&>))
+import Classh.Internal.TShow (tshow)
 
-import Classh.Internal.TWNum as X
-import Classh.Responsive.WhenTW as X
-import Classh.Color as X
-import Classh.Box.Gradient as X
-import Classh.Cursor as X
-import Classh.Box.TWSize as X
-import Classh.Box.Padding as X
-import Classh.Box.Margin as X
-import Classh.Box.SizingBand as X
-import Classh.Box.Placement as X
-import Classh.Box.Border as X
-import Classh.Box.Shadow as X
-import Classh.Box.Transition as X
-import Classh.Box.Transform as X
-import Classh.WithTransition as X
+import Classh.Internal.TWNum as TWNum
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Color as Color
+import Classh.Box.Gradient as Gradient
+import Classh.Cursor as Cursor
+import Classh.Box.TWSize as TWSize
+import Classh.Box.Padding as Padding
+import Classh.Box.Margin as Margin
+import Classh.Box.SizingBand as SizingBand
+import Classh.Box.Placement as Placement
+import Classh.Box.Border as Border
+import Classh.Box.Shadow as Shadow
+import Classh.Box.Transition as Transition
+import Classh.Box.Transform as Transform
+import Classh.WithTransition as WT
 
 import Control.Lens hiding ((<&>), transform)
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Configuration type for styling HTML box elements (divs, sections, etc.).
diff --git a/src/Classh/Box/Border.hs b/src/Classh/Box/Border.hs
index b03e67d..441091e 100644
--- a/src/Classh/Box/Border.hs
+++ b/src/Classh/Box/Border.hs
@@ -4,6 +4,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Border
+--  Description :  Border styling configuration
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -26,7 +27,12 @@
 --------------------------------------------------------------------------------
 
 module Classh.Box.Border
-  ( module X
+  ( module BStyle
+  , module BWidth
+  , module BColor
+  , module BRadius
+  , module BRing
+  , module BOutline
   -- * The Border type
   , BorderConfig(..)
   -- * Border Sub-Types
@@ -46,19 +52,19 @@ module Classh.Box.Border
   , outline
   ) where
 
-import Classh.Box.Border.Style as X
-import Classh.Box.Border.Width as X
-import Classh.Box.Border.Color as X
-import Classh.Box.Border.Radius as X
-import Classh.Box.Ring as X
-import Classh.Box.Outline as X
+import Classh.Box.Border.Style as BStyle
+import Classh.Box.Border.Width as BWidth
+import Classh.Box.Border.Color as BColor
+import Classh.Box.Border.Radius as BRadius
+import Classh.Box.Ring as BRing
+import Classh.Box.Outline as BOutline
 
-import Classh.Internal.Chain
-import Classh.Class.ShowTW
-import Classh.Responsive.WhenTW
+import Classh.Internal.Chain ((<&>))
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Responsive.WhenTW as WhenTW
 
 import Control.Lens hiding ((<&>))
-import Data.Default
+import Data.Default (Default(..))
 
 --------------------------------------------------------------------------------
 -- |
diff --git a/src/Classh/Box/Border/Color.hs b/src/Classh/Box/Border/Color.hs
index a749e9f..93c202a 100644
--- a/src/Classh/Box/Border/Color.hs
+++ b/src/Classh/Box/Border/Color.hs
@@ -1,15 +1,22 @@
 {-# LANGUAGE FlexibleInstances #-}
 
+-- |
+-- Module      : Classh.Box.Border.Color
+-- Description : Border color types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Box.Border.Color where
 
-import Classh.Class.ShowTW
-import Classh.Class.SetSides
-import Classh.Responsive.WhenTW
-import Classh.Internal.Chain
-import Classh.Color
-import Classh.WithTransition
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.SetSides as SetSides
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Internal.Chain ((<&>))
+import Classh.Color as Color
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
-import Data.Default
+import Data.Default (Default(..))
 import Control.Lens (lens, makeLenses)
 
 
diff --git a/src/Classh/Box/Border/Radius.hs b/src/Classh/Box/Border/Radius.hs
index d0adb7b..acbb139 100644
--- a/src/Classh/Box/Border/Radius.hs
+++ b/src/Classh/Box/Border/Radius.hs
@@ -1,17 +1,24 @@
 {-# LANGUAGE FlexibleInstances #-}
 
+-- |
+-- Module      : Classh.Box.Border.Radius
+-- Description : Border radius types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Box.Border.Radius where
 
-import Classh.Class.ShowTW
-import Classh.Class.SetSides
-import Classh.Class.IsCSS
-import Classh.Responsive.WhenTW
-import Classh.Internal.Chain
-import Classh.Internal.CSSSize
-import Classh.Internal.TShow
-import Classh.WithTransition
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.SetSides as SetSides
+import Classh.Class.IsCSS (IsCSS (..))
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Internal.Chain ((<&>))
+import Classh.Internal.CSSSize (CSSSize)
+import Classh.Internal.TShow (tshow)
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
-import Data.Default
+import Data.Default (Default(..))
 import Control.Lens (Lens', lens, makeLenses)
 import qualified Data.Text as T
 
diff --git a/src/Classh/Box/Border/Style.hs b/src/Classh/Box/Border/Style.hs
index 3d9bd49..ea855c2 100644
--- a/src/Classh/Box/Border/Style.hs
+++ b/src/Classh/Box/Border/Style.hs
@@ -1,8 +1,15 @@
+-- |
+-- Module      : Classh.Box.Border.Style
+-- Description : Border style types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Box.Border.Style where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Border Style options, eg BSolid ==> "border-solid"
diff --git a/src/Classh/Box/Border/Width.hs b/src/Classh/Box/Border/Width.hs
index 92596b0..1f269d6 100644
--- a/src/Classh/Box/Border/Width.hs
+++ b/src/Classh/Box/Border/Width.hs
@@ -1,17 +1,24 @@
 {-# LANGUAGE FlexibleInstances #-}
 
+-- |
+-- Module      : Classh.Box.Border.Width
+-- Description : Border width types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Box.Border.Width where
 
-import Classh.Class.ShowTW
-import Classh.Class.SetSides
-import Classh.Class.IsCSS
-import Classh.Responsive.WhenTW
-import Classh.Internal.Chain
-import Classh.Internal.CSSSize
-import Classh.Internal.TShow
-import Classh.WithTransition
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.SetSides as SetSides
+import Classh.Class.IsCSS (IsCSS (..))
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Internal.Chain ((<&>))
+import Classh.Internal.CSSSize (CSSSize)
+import Classh.Internal.TShow (tshow)
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
-import Data.Default
+import Data.Default (Default(..))
 import Control.Lens (lens, makeLenses)
 import qualified Data.Text as T
 
diff --git a/src/Classh/Box/DivInt.hs b/src/Classh/Box/DivInt.hs
index a09bc2a..5e4a257 100644
--- a/src/Classh/Box/DivInt.hs
+++ b/src/Classh/Box/DivInt.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Border
+--  Description :  Fraction denominator types for sizing
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -21,10 +22,10 @@
 
 module Classh.Box.DivInt where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | (w|h)-'DivInt', eg. w-11/12
diff --git a/src/Classh/Box/Gradient.hs b/src/Classh/Box/Gradient.hs
index 6c6f590..46b81a2 100644
--- a/src/Classh/Box/Gradient.hs
+++ b/src/Classh/Box/Gradient.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Gradient
+--  Description :  CSS gradient types and constructors
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -60,11 +61,11 @@ module Classh.Box.Gradient
   , gradientFrom
   ) where
 
-import Classh.Class.ShowTW
-import Classh.Color
-import Classh.Internal.TShow
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Color as Color
+import Classh.Internal.TShow (tshow)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Direction for linear gradients.
diff --git a/src/Classh/Box/Margin.hs b/src/Classh/Box/Margin.hs
index 77f4aab..b16bea4 100644
--- a/src/Classh/Box/Margin.hs
+++ b/src/Classh/Box/Margin.hs
@@ -5,6 +5,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Margin
+--  Description :  Margin configuration for box model
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -42,17 +43,17 @@ module Classh.Box.Margin
   , marginR
   ) where
 
-import Classh.Internal.Chain
-import Classh.Class.ShowTW
-import Classh.Class.SetSides
-import Classh.Responsive.WhenTW
-import Classh.WithTransition
+import Classh.Internal.Chain ((<&>))
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.SetSides as SetSides
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
 
 import Classh.Box.TWSize as X
 
 import Control.Lens hiding ((<&>))
-import Data.Default
+import Data.Default (Default(..))
 
 -- | > == BoxMargin [] [] [] []
 instance Default BoxMargin where
diff --git a/src/Classh/Box/Outline.hs b/src/Classh/Box/Outline.hs
index 1a50312..5e10274 100644
--- a/src/Classh/Box/Outline.hs
+++ b/src/Classh/Box/Outline.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Outline
+--  Description :  Outline styling configuration
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -21,9 +22,9 @@
 
 module Classh.Box.Outline where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Outline style
diff --git a/src/Classh/Box/Padding.hs b/src/Classh/Box/Padding.hs
index c253e82..1764d78 100644
--- a/src/Classh/Box/Padding.hs
+++ b/src/Classh/Box/Padding.hs
@@ -5,6 +5,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Padding
+--  Description :  Padding configuration for box model
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -43,18 +44,18 @@ module Classh.Box.Padding
   ) where
 
 
-import Classh.Internal.Chain
-import Classh.Class.ShowTW
-import Classh.Class.SetSides
-import Classh.Class.CompileStyle
-import Classh.Responsive.WhenTW
-import Classh.WithTransition
+import Classh.Internal.Chain ((<&>))
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.SetSides as SetSides
+import Classh.Class.CompileStyle as CompileStyle
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
 
 import Classh.Box.TWSize as X
 
 import Control.Lens hiding ((<&>))
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/Box/Placement.hs b/src/Classh/Box/Placement.hs
index 627c70f..024900c 100644
--- a/src/Classh/Box/Placement.hs
+++ b/src/Classh/Box/Placement.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Placement
+--  Description :  Element placement and alignment
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -30,7 +31,8 @@
 
 
 module Classh.Box.Placement
-  ( module X
+  ( module Justify
+  , module Align
   , Matrix33(..)
   , topLeft
   , middleLeft
@@ -44,11 +46,11 @@ module Classh.Box.Placement
   , centeredOnly
   ) where
 
-import Classh.Box.Placement.Justify as X 
-import Classh.Box.Placement.Align as X
+import Classh.Box.Placement.Align as Align
+import Classh.Box.Placement.Justify as Justify
 
-import Classh.Responsive.WhenTW
-import Classh.Responsive.ZipScreens 
+import Classh.Responsive.WhenTW (WhenTW)
+import Classh.Responsive.ZipScreens (only)
 
 
 -- | Eg tic tac toe, except we use to describe position of element
diff --git a/src/Classh/Box/Placement/Align.hs b/src/Classh/Box/Placement/Align.hs
index b881519..4605878 100644
--- a/src/Classh/Box/Placement/Align.hs
+++ b/src/Classh/Box/Placement/Align.hs
@@ -3,6 +3,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Placement.Align
+--  Description :  Alignment types for element positioning
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -31,9 +32,9 @@
 --------------------------------------------------------------------------------
 module Classh.Box.Placement.Align where
 
-import Classh.Class.ShowTW
+import Classh.Class.ShowTW (ShowTW(..))
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T 
 
 -- | > == A_Start
diff --git a/src/Classh/Box/Placement/Justify.hs b/src/Classh/Box/Placement/Justify.hs
index 08a1ff9..0ebf00a 100644
--- a/src/Classh/Box/Placement/Justify.hs
+++ b/src/Classh/Box/Placement/Justify.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Placement.Justify
+--  Description :  Justify types for element positioning
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -31,9 +32,9 @@
 
 module Classh.Box.Placement.Justify where
 
-import Classh.Class.ShowTW
+import Classh.Class.ShowTW (ShowTW(..))
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | > J_Start
diff --git a/src/Classh/Box/Ring.hs b/src/Classh/Box/Ring.hs
index d32e90a..dfc5ab7 100644
--- a/src/Classh/Box/Ring.hs
+++ b/src/Classh/Box/Ring.hs
@@ -4,6 +4,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Ring
+--  Description :  Ring styling configuration
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -28,15 +29,15 @@
 
 module Classh.Box.Ring where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
-import Classh.Internal.Chain
-import Classh.Responsive.WhenTW
-import Classh.Color
-import Classh.WithTransition
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
+import Classh.Internal.Chain ((<&>))
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Color as Color
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
 import Control.Lens (makeLenses)
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Ring width
diff --git a/src/Classh/Box/Shadow.hs b/src/Classh/Box/Shadow.hs
index f53e203..1c4193c 100644
--- a/src/Classh/Box/Shadow.hs
+++ b/src/Classh/Box/Shadow.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Shadow
+--  Description :  Shadow styling types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -21,9 +22,9 @@
 
 module Classh.Box.Shadow where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Box shadow options
diff --git a/src/Classh/Box/Sizing/BoxSizing.hs b/src/Classh/Box/Sizing/BoxSizing.hs
index 4101ae4..935dedd 100644
--- a/src/Classh/Box/Sizing/BoxSizing.hs
+++ b/src/Classh/Box/Sizing/BoxSizing.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Sizing.BoxSizing
+--  Description :  Box sizing types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -34,13 +35,13 @@ module Classh.Box.Sizing.BoxSizing
   , height
   ) where 
 
-import Classh.Internal.Chain
-import Classh.Class.ShowTW
-import Classh.Responsive.WhenTW
-import Classh.Box.TWSize
-import Classh.WithTransition
+import Classh.Internal.Chain ((<&>))
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Box.TWSize as TWSize
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
-import Data.Default
+import Data.Default (Default(..))
 import Control.Lens (makeLenses)
 
 -- | Holds information on target sizing (transitionable), which will be overrided by constraints
diff --git a/src/Classh/Box/Sizing/BoxSizingConstraint.hs b/src/Classh/Box/Sizing/BoxSizingConstraint.hs
index 48177ac..14b4d1b 100644
--- a/src/Classh/Box/Sizing/BoxSizingConstraint.hs
+++ b/src/Classh/Box/Sizing/BoxSizingConstraint.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Sizing.BoxSizingConstraint 
+--  Description :  Box sizing constraint types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -33,10 +34,10 @@ module Classh.Box.Sizing.BoxSizingConstraint
   ) where
 
 import Classh.Box.Sizing.DimensionConstraint as X
-import Classh.Responsive.WhenTW
-import Classh.WithTransition
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.WithTransition as WT
 import Control.Lens (makeLenses)
-import Data.Default
+import Data.Default (Default(..))
 
 -- | > == BoxSizingConstraint DC_none DC_none
 instance Default BoxSizingConstraint where
diff --git a/src/Classh/Box/Sizing/DimensionConstraint.hs b/src/Classh/Box/Sizing/DimensionConstraint.hs
index 6b41f81..f94ddb4 100644
--- a/src/Classh/Box/Sizing/DimensionConstraint.hs
+++ b/src/Classh/Box/Sizing/DimensionConstraint.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Sizing.DimensionConstraint 
+--  Description :  Dimension constraint types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -25,9 +26,9 @@
 
 module Classh.Box.Sizing.DimensionConstraint where
 
-import Classh.Internal.TShow
-import Classh.Class.ShowTW 
-import Data.Default
+import Classh.Internal.TShow (tshow)
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- TODO: this is technically wrong: there are different classes for width vs height but oh well for now
diff --git a/src/Classh/Box/SizingBand.hs b/src/Classh/Box/SizingBand.hs
index f808e13..048f1b3 100644
--- a/src/Classh/Box/SizingBand.hs
+++ b/src/Classh/Box/SizingBand.hs
@@ -3,6 +3,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Sizing.BoxSizing
+--  Description :  Responsive sizing band configuration
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -38,24 +39,25 @@ module Classh.Box.SizingBand
   , maxSize
   , minSize
   , size     
-  , module X
+  , module BoxSizing
+  , module BoxSizingConstraint
+  , module TWSize
   ) where
 
---- instead this will just import all pieces 
-import Classh.Box.Sizing.BoxSizing as X
-import Classh.Box.Sizing.BoxSizingConstraint as X
+import Classh.Box.Sizing.BoxSizing as BoxSizing
+import Classh.Box.Sizing.BoxSizingConstraint as BoxSizingConstraint
 
-import Classh.Class.ShowTW
-import Classh.Responsive.WhenTW
-import Classh.Internal.Chain
-import Classh.Responsive.ZipScreens
-import Classh.WithTransition
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Internal.Chain ((<&>))
+import Classh.Responsive.ZipScreens as ZipScreens
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
 
-import Classh.Box.TWSize as X
+import Classh.Box.TWSize as TWSize
 
 import Control.Lens (makeLenses)
-import Data.Default
+import Data.Default (Default(..))
 
 -- move to shorthand?
 fitToContents :: (WhenTW (WithTransition TWSizeOrFraction), WhenTW (WithTransition TWSizeOrFraction))
diff --git a/src/Classh/Box/TWSize.hs b/src/Classh/Box/TWSize.hs
index 14a2c58..01594e9 100644
--- a/src/Classh/Box/TWSize.hs
+++ b/src/Classh/Box/TWSize.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.TWSize
+--  Description :  Tailwind spacing and sizing scale
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -28,21 +29,22 @@
 
 
 module Classh.Box.TWSize
-  ( module X
+  ( module CSSSize
+  , module DivInt
   , twSize'
   , TWSize(..)
   , TWSizeOrFraction(..)
   ) where
 
-import Classh.Class.HasCSSSize 
-import Classh.Class.ShowTW
-import Classh.Class.IsCSS
-import Classh.Internal.TShow
+import Classh.Class.HasCSSSize (HasCSSSize (..))
+import Classh.Class.ShowTW (ShowTW (..))
+import Classh.Class.IsCSS (IsCSS (..))
+import Classh.Internal.TShow (tshow)
 
-import Classh.Internal.CSSSize as X
-import Classh.Box.DivInt as X
+import Classh.Internal.CSSSize as CSSSize
+import Classh.Box.DivInt as DivInt
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Use a TWSize where the config is expecting a TWSizeOrFraction
diff --git a/src/Classh/Box/Transform.hs b/src/Classh/Box/Transform.hs
index ddc060c..8873cb2 100644
--- a/src/Classh/Box/Transform.hs
+++ b/src/Classh/Box/Transform.hs
@@ -2,6 +2,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Transform
+--  Description :  CSS transform types and configuration
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -41,18 +42,18 @@ module Classh.Box.Transform
   , transformOrigin
   ) where
 
-import Classh.Class.ShowTW
-import Classh.Class.CompileStyle
-import Classh.Internal.TShow
-import Classh.Internal.Chain
-import Classh.Responsive.WhenTW
-import Classh.WithTransition
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.CompileStyle as CompileStyle
+import Classh.Internal.TShow (tshow)
+import Classh.Internal.Chain ((<&>))
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.WithTransition as WT
 import Classh.Box.Transition (TransitionProperty(..))
 import Classh.Box.TWSize (TWSize, DivInt(..))
 import Classh.Internal.CSSSize (CSSSize)
 import Classh.Class.IsCSS (renderCSS)
 import Control.Lens hiding ((<&>))
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Scale transform
diff --git a/src/Classh/Box/Transition.hs b/src/Classh/Box/Transition.hs
index cab5b1c..2e6d447 100644
--- a/src/Classh/Box/Transition.hs
+++ b/src/Classh/Box/Transition.hs
@@ -3,6 +3,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Box.Transition
+--  Description :  CSS transition configuration
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -24,12 +25,12 @@
 
 module Classh.Box.Transition where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
-import Classh.Internal.Chain
-import Classh.Responsive.WhenTW
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
+import Classh.Internal.Chain ((<&>))
+import Classh.Responsive.WhenTW (WhenTW, renderWhenTW)
 import Control.Lens (makeLenses)
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Transition property - which properties to transition
diff --git a/src/Classh/Class/CompileStyle.hs b/src/Classh/Class/CompileStyle.hs
index ad8b1ce..05155ea 100644
--- a/src/Classh/Class/CompileStyle.hs
+++ b/src/Classh/Class/CompileStyle.hs
@@ -1,3 +1,10 @@
+-- |
+-- Module      : Classh.Class.CompileStyle
+-- Description : CompileStyle typeclass for CSS compilation
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Class.CompileStyle where
 
 import qualified Data.Text as T 
diff --git a/src/Classh/Class/HasCSSSize.hs b/src/Classh/Class/HasCSSSize.hs
index 0e19bae..d5217b4 100644
--- a/src/Classh/Class/HasCSSSize.hs
+++ b/src/Classh/Class/HasCSSSize.hs
@@ -1,6 +1,13 @@
+-- |
+-- Module      : Classh.Class.HasCSSSize
+-- Description : HasCSSSize typeclass for sized types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Class.HasCSSSize where
 
-import Classh.Internal.CSSSize
+import Classh.Internal.CSSSize (CSSSize (Percent, Pixel, Rem, Vh, Vw))
 
 -- | Represents the ability to use raw CSS Sizing in a given instance/context
 class HasCSSSize tw where
diff --git a/src/Classh/Class/HasCustom.hs b/src/Classh/Class/HasCustom.hs
index 205e319..45feb8a 100644
--- a/src/Classh/Class/HasCustom.hs
+++ b/src/Classh/Class/HasCustom.hs
@@ -1,6 +1,13 @@
+-- |
+-- Module      : Classh.Class.HasCustom
+-- Description : HasCustom typeclass for custom CSS escape hatch
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Class.HasCustom where
 
-import Control.Lens 
+import Control.Lens (Lens')
 import qualified Data.Text as T
 
 -- | Allows for shorter applications of custom classes to a Box or Text 
diff --git a/src/Classh/Class/IsCSS.hs b/src/Classh/Class/IsCSS.hs
index d554729..ba0c819 100644
--- a/src/Classh/Class/IsCSS.hs
+++ b/src/Classh/Class/IsCSS.hs
@@ -1,3 +1,10 @@
+-- |
+-- Module      : Classh.Class.IsCSS
+-- Description : IsCSS typeclass for CSS representable types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Class.IsCSS where
 
 import qualified Data.Text as T
diff --git a/src/Classh/Class/SetSides.hs b/src/Classh/Class/SetSides.hs
index bd8982f..d59f957 100644
--- a/src/Classh/Class/SetSides.hs
+++ b/src/Classh/Class/SetSides.hs
@@ -1,10 +1,17 @@
 {-# LANGUAGE MultiParamTypeClasses #-}
 {-# LANGUAGE FunctionalDependencies #-}
 
+-- |
+-- Module      : Classh.Class.SetSides
+-- Description : SetSides typeclass for side-specific property setters
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Class.SetSides where
 
-import Classh.Responsive.WhenTW
-import Control.Lens
+import Classh.Responsive.WhenTW (WhenTW)
+import Control.Lens (Lens')
 
 -- | This class allows for shorthand for a config that is based on sides, such
 -- | as padding or margin or border
diff --git a/src/Classh/Class/ShowTW.hs b/src/Classh/Class/ShowTW.hs
index 4e5dea3..fab44df 100644
--- a/src/Classh/Class/ShowTW.hs
+++ b/src/Classh/Class/ShowTW.hs
@@ -1,3 +1,10 @@
+-- |
+-- Module      : Classh.Class.ShowTW
+-- Description : ShowTW typeclass for Tailwind class rendering
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Class.ShowTW where
 
 import qualified Data.Text as T
diff --git a/src/Classh/Color.hs b/src/Classh/Color.hs
index 6e69e07..8a88c8f 100644
--- a/src/Classh/Color.hs
+++ b/src/Classh/Color.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Color
+--  Description :  Color types and constructors for Tailwind CSS colors
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -30,10 +31,10 @@ module Classh.Color
   , hex
   ) where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Shorthand application of hex code color 
diff --git a/src/Classh/Cursor.hs b/src/Classh/Cursor.hs
index 0cb1c5e..424fb20 100644
--- a/src/Classh/Cursor.hs
+++ b/src/Classh/Cursor.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Cursor
+--  Description :  Cursor style types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -21,10 +22,10 @@
 
 module Classh.Cursor where
 
-import Classh.Class.ShowTW
-import Classh.Internal.Utils
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.Utils (toKebabCase)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 data CursorStyle
diff --git a/src/Classh/Grid.hs b/src/Classh/Grid.hs
index c8de6a1..b2e71f4 100644
--- a/src/Classh/Grid.hs
+++ b/src/Classh/Grid.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Grid
+--  Description :  Grid layout column types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -20,9 +21,9 @@
 
 module Classh.Grid where
 
-import Classh.Class.ShowTW
+import Classh.Class.ShowTW (ShowTW(..))
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | The number of Columns to split a row into. Classh will detect the use of this construct
diff --git a/src/Classh/Internal/CSSSize.hs b/src/Classh/Internal/CSSSize.hs
index 131686c..6c9e20d 100644
--- a/src/Classh/Internal/CSSSize.hs
+++ b/src/Classh/Internal/CSSSize.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Internal.CSSSize
+--  Description :  CSS size representation types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -22,10 +23,10 @@
 
 module Classh.Internal.CSSSize where
 
-import Classh.Internal.TShow
+import Classh.Internal.TShow (tshow)
 
 -- we should make a Module tree: Classh.TWSize.(TWSize | CSSSize | Fraction)
-import Classh.Class.IsCSS
+import Classh.Class.IsCSS (IsCSS(..))
 
 -- | For use with Tailwind sizes that allow use of CSS size
 data CSSSize
diff --git a/src/Classh/Internal/Chain.hs b/src/Classh/Internal/Chain.hs
index 45b9339..58154db 100644
--- a/src/Classh/Internal/Chain.hs
+++ b/src/Classh/Internal/Chain.hs
@@ -1,3 +1,10 @@
+-- |
+-- Module      : Classh.Internal.Chain
+-- Description : Chain utility for function composition
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Internal.Chain where
 
 import qualified Data.Text as T 
diff --git a/src/Classh/Internal/TShow.hs b/src/Classh/Internal/TShow.hs
index 363d007..1e42eff 100644
--- a/src/Classh/Internal/TShow.hs
+++ b/src/Classh/Internal/TShow.hs
@@ -1,3 +1,10 @@
+-- |
+-- Module      : Classh.Internal.TShow
+-- Description : Type-level show utilities
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Internal.TShow where
 
 import qualified Data.Text as T
diff --git a/src/Classh/Internal/TWNum.hs b/src/Classh/Internal/TWNum.hs
index 8b76a25..cd31397 100644
--- a/src/Classh/Internal/TWNum.hs
+++ b/src/Classh/Internal/TWNum.hs
@@ -1,17 +1,20 @@
---------------------------------------------------------------------------------
 -- |
---  Module      :  Classh.Internal.TWNum
---  common numerical system used across different Tailwind classes. This is just
---  a discrete version of Int
---------------------------------------------------------------------------------
+-- Module      : Classh.Internal.TWNum
+-- Description : Tailwind numeric value types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+--
+-- Common numerical system used across different Tailwind classes. This is just
+-- a discrete version of Int.
 
 
 module Classh.Internal.TWNum where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/Internal/Utils.hs b/src/Classh/Internal/Utils.hs
index 9bf8af5..bfce324 100644
--- a/src/Classh/Internal/Utils.hs
+++ b/src/Classh/Internal/Utils.hs
@@ -1,6 +1,13 @@
+-- |
+-- Module      : Classh.Internal.Utils
+-- Description : Internal utility functions
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Internal.Utils where
 
-import Data.Char
+import Data.Char (toLower, isUpper)
 
 toKebabCase :: String -> String
 toKebabCase [] = []
diff --git a/src/Classh/Responsive/WhenTW.hs b/src/Classh/Responsive/WhenTW.hs
index 98491d7..05c2cf9 100644
--- a/src/Classh/Responsive/WhenTW.hs
+++ b/src/Classh/Responsive/WhenTW.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Responsive.WhenTW 
+--  Description :  Conditional responsive class application
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -22,8 +23,8 @@
 
 module Classh.Responsive.WhenTW where
 
-import Classh.Internal.Chain
-import Classh.Class.ShowTW
+import Classh.Internal.Chain ((<&>))
+import Classh.Class.ShowTW (ShowTW(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/Responsive/ZipScreens.hs b/src/Classh/Responsive/ZipScreens.hs
index 9bb2e01..843058f 100644
--- a/src/Classh/Responsive/ZipScreens.hs
+++ b/src/Classh/Responsive/ZipScreens.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Responsive.WhenTW 
+--  Description :  Responsive breakpoint screen types and operators
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -24,8 +25,8 @@
 module Classh.Responsive.ZipScreens where
 
 import Classh.Responsive.WhenTW as X 
-import Classh.Class.ShowTW 
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Eg
diff --git a/src/Classh/Setters.hs b/src/Classh/Setters.hs
index 762488b..2511314 100644
--- a/src/Classh/Setters.hs
+++ b/src/Classh/Setters.hs
@@ -7,6 +7,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Setters
+--  Description :  Lens setters for BoxConfig and TextConfigTW
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -35,9 +36,9 @@
 
 module Classh.Setters where
 
-import Classh.Responsive.WhenTW
-import Classh.Responsive.ZipScreens
-import Classh.WithTransition
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Responsive.ZipScreens as ZipScreens
+import Classh.WithTransition as WT
 import Control.Lens hiding (only)
 
 -- | Append a list to existing WhenTW field of a config (for non-transitionable fields)
diff --git a/src/Classh/Shorthand.hs b/src/Classh/Shorthand.hs
index b226122..e7e0f28 100644
--- a/src/Classh/Shorthand.hs
+++ b/src/Classh/Shorthand.hs
@@ -3,6 +3,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Shorthand
+--  Description :  Shorthand aliases for common operations
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -29,10 +30,10 @@
 
 module Classh.Shorthand where
 
-import Classh.Text
-import Classh.Box
-import Classh.Setters
-import Classh.Class.SetSides
+import Classh.Text as Text
+import Classh.Box as Box
+import Classh.Setters as Setters
+import Classh.Class.SetSides as SetSides
 
 import Control.Lens (Lens')
 -- this is purely semantic compression for those familiar with Classh
diff --git a/src/Classh/Text.hs b/src/Classh/Text.hs
index 1495918..bd31737 100644
--- a/src/Classh/Text.hs
+++ b/src/Classh/Text.hs
@@ -3,6 +3,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text
+--  Description :  Text styling configuration type and lenses
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -260,9 +261,15 @@ module Classh.Text
   (
     -- * Core Config Type 
     TextConfigTW(..)
-    -- * Re-exports 
-  , module X
-  -- * Auto Generated Lenses 
+    -- * Re-exports
+  , module Color
+  , module Cursor
+  , module Decoration
+  , module FontStyle
+  , module Font
+  , module Size
+  , module Weight
+  -- * Auto Generated Lenses
   , text_size
   , text_weight
   , text_font
@@ -270,25 +277,25 @@ module Classh.Text
   , text_decoration
   , text_style
   , text_cursor
-  , text_custom  
+  , text_custom
   ) where
 
-import Classh.Class.HasCustom
-import Classh.Class.CompileStyle
-import Classh.Class.ShowTW
-import Classh.Internal.Chain
-import Classh.Responsive.WhenTW
+import Classh.Class.HasCustom as HasCustom
+import Classh.Class.CompileStyle as CompileStyle
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.Chain ((<&>))
+import Classh.Responsive.WhenTW as WhenTW
 
-import Classh.Color as X
-import Classh.Cursor as X
-import Classh.Text.Decoration as X
-import Classh.Text.FontStyle as X
-import Classh.Text.Font as X
-import Classh.Text.Size as X
-import Classh.Text.Weight as X
+import Classh.Color as Color
+import Classh.Cursor as Cursor
+import Classh.Text.Decoration as Decoration
+import Classh.Text.FontStyle as FontStyle
+import Classh.Text.Font as Font
+import Classh.Text.Size as Size
+import Classh.Text.Weight as Weight
 
 import Control.Lens (makeLenses)
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 instance ShowTW TextConfigTW where
diff --git a/src/Classh/Text/Decoration.hs b/src/Classh/Text/Decoration.hs
index 34096d8..1a1807f 100644
--- a/src/Classh/Text/Decoration.hs
+++ b/src/Classh/Text/Decoration.hs
@@ -3,6 +3,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Decoration
+--  Description :  Text decoration configuration
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -38,21 +39,25 @@ module Classh.Text.Decoration
   , textDec_thickness
   , textDec_offset
   , textDec_style
-  , module X
+  , module Color
+  , module Offset
+  , module Thickness
+  , module Style
+  , module LineType
   ) where
 
-import Classh.Class.ShowTW
-import Classh.Responsive.WhenTW
-import Classh.Internal.Chain
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Responsive.WhenTW as WhenTW
+import Classh.Internal.Chain ((<&>))
 
-import Classh.Color as X 
-import Classh.Text.Decoration.Offset as X
-import Classh.Text.Decoration.Thickness as X
-import Classh.Text.Decoration.Style as X
-import Classh.Text.Decoration.LineType as X
+import Classh.Color as Color
+import Classh.Text.Decoration.Offset as Offset
+import Classh.Text.Decoration.Thickness as Thickness
+import Classh.Text.Decoration.Style as Style
+import Classh.Text.Decoration.LineType as LineType
 
 import Control.Lens (makeLenses)
-import Data.Default
+import Data.Default (Default(..))
 
 -- | > TextDecorationTW [] [] [] [] []
 instance Default TextDecorationTW where
diff --git a/src/Classh/Text/Decoration/LineType.hs b/src/Classh/Text/Decoration/LineType.hs
index 4ac3eb4..e535ee1 100644
--- a/src/Classh/Text/Decoration/LineType.hs
+++ b/src/Classh/Text/Decoration/LineType.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Decoration.LineType
+--  Description :  Text decoration line types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -20,10 +21,10 @@
 
 module Classh.Text.Decoration.LineType where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | > == NoUnderline
diff --git a/src/Classh/Text/Decoration/Offset.hs b/src/Classh/Text/Decoration/Offset.hs
index 062f52d..89d9a28 100644
--- a/src/Classh/Text/Decoration/Offset.hs
+++ b/src/Classh/Text/Decoration/Offset.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Decoration.Offset
+--  Description :  Text decoration offset types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -19,10 +20,10 @@
 
 module Classh.Text.Decoration.Offset where
 
-import Classh.Class.ShowTW
-import Classh.Class.IsCSS
-import Classh.Internal.CSSSize
-import Classh.Internal.TWNum
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.IsCSS (IsCSS(..))
+import Classh.Internal.CSSSize (CSSSize)
+import Classh.Internal.TWNum (TWNum (..))
 
 {-
 TODOS:
@@ -30,7 +31,7 @@ Could TWNum have a variant of CSSSize ? then this almost becomes irrelevant as a
 of the larger config?
 -}
 
-import Data.Default
+import Data.Default (Default(..))
 
 
 instance Default TextDecOffset where
diff --git a/src/Classh/Text/Decoration/Style.hs b/src/Classh/Text/Decoration/Style.hs
index fa860c0..bd2afb4 100644
--- a/src/Classh/Text/Decoration/Style.hs
+++ b/src/Classh/Text/Decoration/Style.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Decoration.Style
+--  Description :  Text decoration style types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -20,10 +21,10 @@
 
 module Classh.Text.Decoration.Style where
 
-import Classh.Class.ShowTW
-import Classh.Internal.TShow
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.TShow (tshow)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | > == Solid 
diff --git a/src/Classh/Text/Decoration/Thickness.hs b/src/Classh/Text/Decoration/Thickness.hs
index d9e4c4b..d5fe6d7 100644
--- a/src/Classh/Text/Decoration/Thickness.hs
+++ b/src/Classh/Text/Decoration/Thickness.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Decoration.Thickness
+--  Description :  Text decoration thickness types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -19,13 +20,13 @@
 
 module Classh.Text.Decoration.Thickness where
 
-import Classh.Class.ShowTW
-import Classh.Class.IsCSS
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Class.IsCSS (IsCSS(..))
 
-import Classh.Internal.TWNum as X
-import Classh.Internal.CSSSize as X
+import Classh.Internal.TWNum as TWNum
+import Classh.Internal.CSSSize as CSSSize
 
-import Data.Default
+import Data.Default (Default(..))
 
 -- | > == TextDecThickness TW1 ==> "decoration-1"
 instance Default TextDecThickness where
diff --git a/src/Classh/Text/Font.hs b/src/Classh/Text/Font.hs
index f613a0c..0d34e8f 100644
--- a/src/Classh/Text/Font.hs
+++ b/src/Classh/Text/Font.hs
@@ -2,6 +2,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Font
+--  Description :  Font family types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -24,10 +25,10 @@
 
 module Classh.Text.Font where
 
-import Classh.Internal.TShow
-import Classh.Class.ShowTW
+import Classh.Internal.TShow (tshow)
+import Classh.Class.ShowTW (ShowTW(..))
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/Text/FontStyle.hs b/src/Classh/Text/FontStyle.hs
index 8e74850..a2ce4e1 100644
--- a/src/Classh/Text/FontStyle.hs
+++ b/src/Classh/Text/FontStyle.hs
@@ -1,9 +1,16 @@
+-- |
+-- Module      : Classh.Text.FontStyle
+-- Description : Font style types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.Text.FontStyle where
 
-import Classh.Class.ShowTW
-import Classh.Internal.Utils
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.Utils (toKebabCase)
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/Text/Size.hs b/src/Classh/Text/Size.hs
index 8e621ac..c71c685 100644
--- a/src/Classh/Text/Size.hs
+++ b/src/Classh/Text/Size.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Size
+--  Description :  Text size scale types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -22,9 +23,9 @@
 module Classh.Text.Size where
 
 
-import Classh.Class.ShowTW
+import Classh.Class.ShowTW (ShowTW(..))
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | TODO: when this inevitably becomes its own package, make it easy to not import Defaults and make your own
diff --git a/src/Classh/Text/Weight.hs b/src/Classh/Text/Weight.hs
index 5836954..1c10331 100644
--- a/src/Classh/Text/Weight.hs
+++ b/src/Classh/Text/Weight.hs
@@ -1,6 +1,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.Text.Weight
+--  Description :  Font weight types
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -20,10 +21,10 @@
 
 module Classh.Text.Weight where
 
-import Classh.Internal.TShow
-import Classh.Class.ShowTW
+import Classh.Internal.TShow (tshow)
+import Classh.Class.ShowTW (ShowTW(..))
 
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | > == Normal
diff --git a/src/Classh/TextPosition.hs b/src/Classh/TextPosition.hs
index 4a01edf..133e4c4 100644
--- a/src/Classh/TextPosition.hs
+++ b/src/Classh/TextPosition.hs
@@ -1,41 +1,57 @@
+-- |
+-- Module      : Classh.TextPosition
+-- Description : Text position and layout properties
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition
-  ( module X
-  -- TODO
+  ( module Clamp
+  , module Content
+  , module Hyphen
+  , module Lead
+  , module TAlign
+  , module VAlign
+  , module TOverflow
+  , module Track
+  , module WhiteSpace
+  , module WordBreak
+  , module Wrap
   , TextPosition(..)
-  , tp_track 
+  , tp_track
   , tp_clamp
   , tp_lineHeight
-  , tp_position  
-  , tp_overflow  
-  , tp_wrap      
-  , tp_indent    
-  , tp_wordBreak 
+  , tp_position
+  , tp_overflow
+  , tp_wrap
+  , tp_indent
+  , tp_wordBreak
   , tp_whiteSpace
-  , tp_hyphen    
-  , tp_content   
-  , tp_custom    
+  , tp_hyphen
+  , tp_content
+  , tp_custom
   )
   where
 
-import Classh.TextPosition.Clamp as X
-import Classh.TextPosition.Content as X
-import Classh.TextPosition.Hyphen as X
-import Classh.TextPosition.Lead as X
-import Classh.TextPosition.TAlign as X
-import Classh.TextPosition.VAlign as X
-import Classh.TextPosition.TOverflow as X
-import Classh.TextPosition.Track as X
-import Classh.TextPosition.WhiteSpace as X
-import Classh.TextPosition.WordBreak as X
-import Classh.TextPosition.Wrap as X
+import Classh.TextPosition.Clamp as Clamp
+import Classh.TextPosition.Content as Content
+import Classh.TextPosition.Hyphen as Hyphen
+import Classh.TextPosition.Lead as Lead
+import Classh.TextPosition.TAlign as TAlign
+import Classh.TextPosition.VAlign as VAlign
+import Classh.TextPosition.TOverflow as TOverflow
+import Classh.TextPosition.Track as Track
+import Classh.TextPosition.WhiteSpace as WhiteSpace
+import Classh.TextPosition.WordBreak as WordBreak
+import Classh.TextPosition.Wrap as Wrap
 
-import Classh.Class.CompileStyle
-import Classh.Class.ShowTW
-import Classh.Internal.Chain
-import Classh.Box.TWSize
-import Classh.Responsive.WhenTW
+import Classh.Class.CompileStyle as CompileStyle
+import Classh.Class.ShowTW (ShowTW(..))
+import Classh.Internal.Chain ((<&>))
+import Classh.Box.TWSize as TWSize
+import Classh.Responsive.WhenTW as WhenTW
 import Control.Lens hiding ((<&>))
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T 
 
 data TextPosition = TextPosition
diff --git a/src/Classh/TextPosition/Clamp.hs b/src/Classh/TextPosition/Clamp.hs
index b4b5b3d..525df34 100644
--- a/src/Classh/TextPosition/Clamp.hs
+++ b/src/Classh/TextPosition/Clamp.hs
@@ -1,8 +1,15 @@
+-- |
+-- Module      : Classh.TextPosition.Clamp
+-- Description : Line clamp types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.Clamp where
 
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/TextPosition/Content.hs b/src/Classh/TextPosition/Content.hs
index ea736bd..8fd3d86 100644
--- a/src/Classh/TextPosition/Content.hs
+++ b/src/Classh/TextPosition/Content.hs
@@ -1,8 +1,15 @@
+-- |
+-- Module      : Classh.TextPosition.Content
+-- Description : Content sizing types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.Content where
 
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/TextPosition/Hyphen.hs b/src/Classh/TextPosition/Hyphen.hs
index afcd2ed..4e1d09a 100644
--- a/src/Classh/TextPosition/Hyphen.hs
+++ b/src/Classh/TextPosition/Hyphen.hs
@@ -1,7 +1,14 @@
+-- |
+-- Module      : Classh.TextPosition.Hyphen
+-- Description : Hyphenation types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.Hyphen where
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 --import qualified Data.Text as T
 
 -- Hyphens
diff --git a/src/Classh/TextPosition/Lead.hs b/src/Classh/TextPosition/Lead.hs
index 0f7eb6d..550f371 100644
--- a/src/Classh/TextPosition/Lead.hs
+++ b/src/Classh/TextPosition/Lead.hs
@@ -1,7 +1,14 @@
+-- |
+-- Module      : Classh.TextPosition.Lead
+-- Description : Line height (leading) types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.Lead where
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- Line Height
diff --git a/src/Classh/TextPosition/TAlign.hs b/src/Classh/TextPosition/TAlign.hs
index 42891d2..c3b6282 100644
--- a/src/Classh/TextPosition/TAlign.hs
+++ b/src/Classh/TextPosition/TAlign.hs
@@ -1,7 +1,14 @@
+-- |
+-- Module      : Classh.TextPosition.TAlign
+-- Description : Text alignment types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.TAlign where
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 
 
 -- Text Align
diff --git a/src/Classh/TextPosition/TOverflow.hs b/src/Classh/TextPosition/TOverflow.hs
index 073b274..36ae58b 100644
--- a/src/Classh/TextPosition/TOverflow.hs
+++ b/src/Classh/TextPosition/TOverflow.hs
@@ -1,8 +1,15 @@
+-- |
+-- Module      : Classh.TextPosition.TOverflow
+-- Description : Text overflow types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.TOverflow where
 
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 
 
 
diff --git a/src/Classh/TextPosition/Track.hs b/src/Classh/TextPosition/Track.hs
index 91623d1..e44443d 100644
--- a/src/Classh/TextPosition/Track.hs
+++ b/src/Classh/TextPosition/Track.hs
@@ -1,8 +1,15 @@
+-- |
+-- Module      : Classh.TextPosition.Track
+-- Description : Letter spacing (tracking) types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.Track where
 
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 
diff --git a/src/Classh/TextPosition/VAlign.hs b/src/Classh/TextPosition/VAlign.hs
index 80275d8..0ba8125 100644
--- a/src/Classh/TextPosition/VAlign.hs
+++ b/src/Classh/TextPosition/VAlign.hs
@@ -1,8 +1,15 @@
+-- |
+-- Module      : Classh.TextPosition.VAlign
+-- Description : Vertical alignment types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.VAlign where
 
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 
 -- Vertical Align
 -- | TODO: Add Sub and Super values as Types accessed via TextConfigTW
diff --git a/src/Classh/TextPosition/WhiteSpace.hs b/src/Classh/TextPosition/WhiteSpace.hs
index 8b2a225..a681f16 100644
--- a/src/Classh/TextPosition/WhiteSpace.hs
+++ b/src/Classh/TextPosition/WhiteSpace.hs
@@ -1,7 +1,14 @@
+-- |
+-- Module      : Classh.TextPosition.WhiteSpace
+-- Description : Whitespace handling types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.WhiteSpace where
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 
 
 -- Whitespace
diff --git a/src/Classh/TextPosition/WordBreak.hs b/src/Classh/TextPosition/WordBreak.hs
index 02597f5..63a8501 100644
--- a/src/Classh/TextPosition/WordBreak.hs
+++ b/src/Classh/TextPosition/WordBreak.hs
@@ -1,7 +1,14 @@
+-- |
+-- Module      : Classh.TextPosition.WordBreak
+-- Description : Word break types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.WordBreak where
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 
 
 -- Word Break (again, could alias Wrap)
diff --git a/src/Classh/TextPosition/Wrap.hs b/src/Classh/TextPosition/Wrap.hs
index c2d2d16..388a864 100644
--- a/src/Classh/TextPosition/Wrap.hs
+++ b/src/Classh/TextPosition/Wrap.hs
@@ -1,7 +1,14 @@
+-- |
+-- Module      : Classh.TextPosition.Wrap
+-- Description : Text wrap types
+-- Copyright   : (c) Galen Sprout, 2024
+-- License     : MIT
+-- Maintainer  : galen.sprout@gmail.com
+
 module Classh.TextPosition.Wrap where
 
-import Classh.Class.ShowTW
-import Data.Default
+import Classh.Class.ShowTW (ShowTW(..))
+import Data.Default (Default(..))
 
 
 
diff --git a/src/Classh/WithTransition.hs b/src/Classh/WithTransition.hs
index d3875f1..538239d 100644
--- a/src/Classh/WithTransition.hs
+++ b/src/Classh/WithTransition.hs
@@ -5,6 +5,7 @@
 --------------------------------------------------------------------------------
 -- |
 --  Module      :  Classh.WithTransition
+--  Description :  Transition wrapper type and operators
 --  Copyright   :  (c) 2024, Galen Sprout
 --  License     :  BSD-style (see end of this file)
 --
@@ -32,11 +33,11 @@
 
 module Classh.WithTransition where
 
-import Classh.Box.Transition
-import Classh.Responsive.WhenTW
-import Classh.Internal.Chain
+import Classh.Box.Transition (TransitionConfig (..), TransitionDelay, TransitionDuration, TransitionProperty (..), TransitionTimingFunction (..))
+import Classh.Responsive.WhenTW (WhenTW)
+import Classh.Internal.Chain ((<&>))
 import Classh.Internal.TShow (tshow)
-import Data.Default
+import Data.Default (Default(..))
 import qualified Data.Text as T
 
 -- | Wraps a value with an optional transition configuration