From 53c783e36793757a5c042ee31a230fa6f402ba8e Mon Sep 17 00:00:00 2001
From: Sean N <sean@isean.co.za>
Date: Fri, 17 Apr 2026 16:32:36 +0200
Subject: [PATCH] Addded correct docstrings to all surface api's

---
 pyproject.toml                    |   2 +-
 src/nitro_ui/core/component.py    |  13 +-
 src/nitro_ui/core/element.py      | 364 ++++++++++++++++++++++--------
 src/nitro_ui/core/parser.py       |  36 +--
 src/nitro_ui/core/partial.py      |  21 +-
 src/nitro_ui/core/slot.py         |   7 +-
 src/nitro_ui/forms/field.py       | 257 ++++++++++++++-------
 src/nitro_ui/styles/style.py      | 128 +++++------
 src/nitro_ui/styles/stylesheet.py | 180 +++++++--------
 src/nitro_ui/styles/theme.py      | 114 +++++-----
 src/nitro_ui/tags/form.py         |  46 +++-
 src/nitro_ui/tags/html.py         |  11 +
 src/nitro_ui/tags/lists.py        |  36 ++-
 src/nitro_ui/tags/table.py        |  38 ++++
 src/nitro_ui/tags/tag_factory.py  |  56 ++++-
 15 files changed, 888 insertions(+), 421 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index cb07716..6580da8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nitro-ui"
-version = "1.0.9"
+version = "1.0.10"
 description = "Build HTML with Python, not strings. Zero-dependency library with type-safe elements, method chaining, and JSON serialization."
 readme = "README.md"
 requires-python = ">=3.8"
diff --git a/src/nitro_ui/core/component.py b/src/nitro_ui/core/component.py
index 76b26e9..688a88b 100644
--- a/src/nitro_ui/core/component.py
+++ b/src/nitro_ui/core/component.py
@@ -233,10 +233,17 @@ def _process_template(
         return result
 
     def template(self) -> List[Any]:
-        """Override to define the component structure.
+        """Override to define this component's structure.
+
+        The method's parameters become declared props: when a caller
+        instantiates the component, non-element positional arguments and
+        matching keyword arguments are routed here. ``Slot()`` markers in
+        the returned tree are replaced with child content; named slots
+        are filled from kwargs of the same name.
 
         Returns:
-            List of HTMLElement instances and/or Slot markers.
-            Use Slot() for default slot, Slot("name") for named slots.
+            A list of ``HTMLElement`` instances and/or ``Slot`` markers
+            that describe the rendered output. Use ``Slot()`` for the
+            default slot and ``Slot("name")`` for named slots.
         """
         return [Slot()]
diff --git a/src/nitro_ui/core/element.py b/src/nitro_ui/core/element.py
index 7949ff1..3571ae0 100644
--- a/src/nitro_ui/core/element.py
+++ b/src/nitro_ui/core/element.py
@@ -130,6 +130,28 @@ def _validate_css_value(value: str) -> bool:
 
 
 class HTMLElement:
+    """Foundation class for every HTML element in NitroUI.
+
+    Owns the tag name, attributes, inline styles, and a list of children
+    (other ``HTMLElement`` instances or plain strings). All mutating methods
+    return ``self`` so calls chain. Instances are also context managers and
+    are serializable to JSON or HTML.
+
+    Children may be passed positionally; keyword arguments become HTML
+    attributes. Python keywords are handled via ``class_name`` / ``for_element``
+    (``class_`` and ``for_`` are also accepted). Underscores in other kwargs
+    are converted to hyphens (``data_value`` -> ``data-value``); SVG
+    camelCase attributes (``view_box`` -> ``viewBox``) are preserved.
+
+    Text content and attribute values are HTML-escaped automatically; only
+    ``render()`` output is unescaped.
+
+    Example:
+        >>> el = HTMLElement("Hello", tag="div", class_name="greeting")
+        >>> el.append(HTMLElement("world", tag="span")).render()
+        '<div class="greeting">Hello<span>world</span></div>'
+    """
+
     __slots__ = [
         "_tag",
         "_children",
@@ -147,6 +169,23 @@ def __init__(
         self_closing: bool = False,
         **attributes: str,
     ):
+        """Create an HTML element with the given tag, children, and attributes.
+
+        Args:
+            *children: Positional children. Each may be an ``HTMLElement``,
+                a string (appended to text content), a list/tuple of either
+                (flattened recursively), or ``None`` (skipped).
+            tag: HTML tag name (e.g. ``"div"``). Must match
+                ``^[a-zA-Z][a-zA-Z0-9-]*$``.
+            self_closing: If ``True``, renders as ``<tag />`` with no
+                closing tag. Adding children emits a warning.
+            **attributes: HTML attributes. See class docstring for the
+                naming conventions applied to keys.
+
+        Raises:
+            ValueError: If ``tag`` is empty, malformed, or a child has an
+                unsupported type.
+        """
         # Attributes that should keep underscores (not convert to hyphens)
         PRESERVE_UNDERSCORE = {"class_name", "for_element"}
 
@@ -240,11 +279,11 @@ def __del__(self) -> None:
             pass
 
     def __enter__(self) -> "HTMLElement":
-        """Context manager entry - returns self for use in with statements."""
+        """Enter a ``with`` block, returning this element for further mutation."""
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb) -> None:
-        """Context manager exit - no cleanup needed."""
+        """Exit a ``with`` block. No cleanup is required."""
         pass
 
     @staticmethod
@@ -257,13 +296,25 @@ def _flatten(items: Union[List[Any], tuple]) -> Iterator[Any]:
                 yield item
 
     def prepend(self, *children: Union["HTMLElement", str, List[Any]]) -> "HTMLElement":
-        """Prepends children to the current tag.
+        """Insert children at the front of this element.
+
+        Mirrors ``append()`` but adds content at the start rather than the
+        end. Strings are prefixed to the existing text content; elements
+        are placed before existing children.
+
+        Args:
+            *children: Elements, strings, or nested lists/tuples. ``None``
+                values are skipped.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
 
         Raises:
-            ValueError: If any child is not an HTMLElement or string
+            ValueError: If any child is not an ``HTMLElement`` or string.
+
+        Example:
+            >>> Div(H2("Body")).prepend(H1("Title")).render()
+            '<div><h1>Title</h1><h2>Body</h2></div>'
         """
         new_children: List[HTMLElement] = []
         text_parts: List[str] = []
@@ -283,13 +334,25 @@ def prepend(self, *children: Union["HTMLElement", str, List[Any]]) -> "HTMLEleme
         return self
 
     def append(self, *children: Union["HTMLElement", str, List[Any]]) -> "HTMLElement":
-        """Appends children to the current tag.
+        """Add children to the end of this element.
+
+        Strings are concatenated to the existing text content; elements
+        are placed after existing children. Nested lists/tuples are
+        flattened so you can splice collections in directly.
+
+        Args:
+            *children: Elements, strings, or nested lists/tuples. ``None``
+                values are skipped.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
 
         Raises:
-            ValueError: If any child is not an HTMLElement or string
+            ValueError: If any child is not an ``HTMLElement`` or string.
+
+        Example:
+            >>> Div().append(H1("Title"), Paragraph("Body")).render()
+            '<div><h1>Title</h1><p>Body</p></div>'
         """
         text_parts: List[str] = []
         for child in self._flatten(children):
@@ -313,16 +376,24 @@ def filter(
         max_depth: int = DEFAULT_MAX_DEPTH,
         _current_depth: int = 0,
     ) -> Iterator["HTMLElement"]:
-        """Yields children (and optionally descendants) that meet the condition.
+        """Yield children (and optionally descendants) matching a predicate.
 
         Args:
-            condition: A callable that takes a child and returns True if it matches
-            recursive: If True, search descendants recursively
-            max_depth: Maximum recursion depth (default 1000) to prevent stack overflow
-            _current_depth: Internal parameter for tracking current depth
+            condition: Called with each child; return ``True`` to yield it.
+            recursive: If ``True``, walk the full subtree; otherwise only
+                direct children are considered.
+            max_depth: Traversal cutoff (default 1000) guarding against
+                circular references.
+
+        Yields:
+            Matching ``HTMLElement`` instances.
 
         Raises:
-            RecursionError: If max_depth is exceeded
+            RecursionError: If ``max_depth`` is exceeded.
+
+        Example:
+            >>> list(page.filter(lambda c: c.tag == "img", recursive=True))
+            [<Image ...>, <Image ...>]
         """
         if _current_depth > max_depth:
             raise RecursionError(
@@ -341,10 +412,15 @@ def filter(
                 )
 
     def remove_all(self, condition: Callable[[Any], bool]) -> "HTMLElement":
-        """Removes all children that meet the condition.
+        """Remove every direct child matching a predicate.
+
+        Only the immediate children are considered (not descendants).
+
+        Args:
+            condition: Called with each child; return ``True`` to remove it.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
         """
         to_remove = list(self.filter(condition))
         for child in to_remove:
@@ -353,31 +429,52 @@ def remove_all(self, condition: Callable[[Any], bool]) -> "HTMLElement":
         return self
 
     def clear(self) -> "HTMLElement":
-        """Clears all children from the tag.
+        """Remove all children from this element.
+
+        Text content is left untouched; use ``text = ""`` to clear it.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
         """
         self._children.clear()
         return self
 
     def pop(self, index: int = 0) -> "HTMLElement":
-        """Pops a child from the tag."""
+        """Remove and return a child by position.
+
+        Args:
+            index: Position to remove from; defaults to the first child.
+
+        Returns:
+            The removed ``HTMLElement``.
+
+        Raises:
+            IndexError: If the element has no children or the index is
+                out of range.
+        """
         return self._children.pop(index)
 
     def first(self) -> Union["HTMLElement", None]:
-        """Returns the first child of the tag."""
+        """Return the first child, or ``None`` if this element has none."""
         return self._children[0] if self._children else None
 
     def last(self) -> Union["HTMLElement", None]:
-        """Returns the last child of the tag."""
+        """Return the last child, or ``None`` if this element has none."""
         return self._children[-1] if self._children else None
 
     def add_attribute(self, key: str, value: str) -> "HTMLElement":
-        """Adds an attribute to the current tag.
+        """Set a single HTML attribute on this element.
+
+        Existing attributes with the same key are overwritten. Setting the
+        ``style`` attribute invalidates the parsed-styles cache used by
+        ``add_style`` / ``get_style``.
+
+        Args:
+            key: Attribute name (use ``class_name`` instead of ``class``).
+            value: Attribute value. Will be HTML-escaped at render time.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
         """
         # Prevent duplicate class attributes from mixed API usage
         if key == "class" and "class_name" in self._attributes:
@@ -392,10 +489,16 @@ def add_attribute(self, key: str, value: str) -> "HTMLElement":
         return self
 
     def add_attributes(self, attributes: List[Tuple[str, str]]) -> "HTMLElement":
-        """Adds multiple attributes to the current tag.
+        """Set multiple HTML attributes in one call.
+
+        Args:
+            attributes: Iterable of ``(key, value)`` pairs.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
+
+        Example:
+            >>> el.add_attributes([("id", "main"), ("data-role", "card")])
         """
         has_style = False
         for key, value in attributes:
@@ -408,10 +511,13 @@ def add_attributes(self, attributes: List[Tuple[str, str]]) -> "HTMLElement":
         return self
 
     def remove_attribute(self, key: str) -> "HTMLElement":
-        """Removes an attribute from the current tag.
+        """Remove an attribute by key. Missing keys are silently ignored.
+
+        Args:
+            key: Attribute name to remove.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
         """
         self._attributes.pop(key, None)
         if key == "style":
@@ -419,11 +525,11 @@ def remove_attribute(self, key: str) -> "HTMLElement":
         return self
 
     def get_attribute(self, key: str) -> Union[str, None]:
-        """Gets an attribute from the current tag."""
+        """Return the value of a named attribute, or ``None`` if absent."""
         return self._attributes.get(key)
 
     def has_attribute(self, key: str) -> bool:
-        """Checks if an attribute exists in the current tag."""
+        """Return ``True`` if the given attribute is set on this element."""
         return key in self._attributes
 
     def _get_styles_dict(self) -> dict:
@@ -446,18 +552,24 @@ def _flush_styles_cache(self) -> None:
                 self._attributes.pop("style", None)
 
     def add_style(self, key: str, value: str) -> "HTMLElement":
-        """
-        Adds a CSS style to the element's inline styles.
+        """Add a single inline CSS declaration to this element.
+
+        Values are checked for common injection patterns (``javascript:``,
+        ``expression(...)``, etc.) before being stored.
 
         Args:
-            key: CSS property name (e.g., 'color', 'font-size')
-            value: CSS property value (e.g., 'red', '14px')
+            key: CSS property name (e.g. ``"color"``, ``"font-size"``).
+            value: CSS property value (e.g. ``"red"``, ``"14px"``).
 
         Returns:
-            self for method chaining
+            This element, for chaining.
 
         Raises:
-            ValueError: If the CSS value contains potentially dangerous content
+            ValueError: If ``value`` contains potentially dangerous content.
+
+        Example:
+            >>> Div().add_style("color", "red").render()
+            '<div style="color: red"></div>'
         """
         if not _validate_css_value(str(value)):
             raise ValueError(
@@ -472,18 +584,20 @@ def add_style(self, key: str, value: str) -> "HTMLElement":
         return self
 
     def add_styles(self, styles: dict) -> "HTMLElement":
-        """
-        Adds multiple CSS styles to the element's inline styles.
+        """Merge a dict of inline CSS declarations into this element.
+
+        Later keys overwrite earlier ones on the element. All values are
+        validated before any are stored.
 
         Args:
-            styles: Dictionary of CSS properties and values
-                   e.g., {"color": "red", "font-size": "14px"}
+            styles: Mapping of CSS property names to values, e.g.
+                ``{"color": "red", "font-size": "14px"}``.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
 
         Raises:
-            ValueError: If any CSS value contains potentially dangerous content
+            ValueError: If any value contains potentially dangerous content.
         """
         for key, value in styles.items():
             if not _validate_css_value(str(value)):
@@ -499,27 +613,29 @@ def add_styles(self, styles: dict) -> "HTMLElement":
         return self
 
     def get_style(self, key: str) -> Union[str, None]:
-        """
-        Gets a specific CSS style value from the element's inline styles.
+        """Return the inline CSS value for a property, or ``None`` if unset.
 
         Args:
-            key: CSS property name
+            key: CSS property name (e.g. ``"color"``).
 
         Returns:
-            The CSS property value or None if not found
+            The stored value, or ``None`` if this element has no such
+            inline declaration.
         """
         styles_dict = self._get_styles_dict()
         return styles_dict.get(key)
 
     def remove_style(self, key: str) -> "HTMLElement":
-        """
-        Removes a CSS style from the element's inline styles.
+        """Remove an inline CSS declaration by property name.
+
+        Missing keys are silently ignored. If this removes the last
+        declaration, the ``style`` attribute is dropped entirely.
 
         Args:
-            key: CSS property name to remove
+            key: CSS property name to remove.
 
         Returns:
-            self for method chaining
+            This element, for chaining.
         """
         styles_dict = self._get_styles_dict()
         styles_dict.pop(key, None)
@@ -582,16 +698,30 @@ def _format_styles(styles_dict: dict) -> str:
         return "; ".join(f"{k}: {v}" for k, v in styles_dict.items())
 
     def generate_id(self) -> None:
-        """Generates an id for the current tag if not already present."""
+        """Assign an auto-generated ``id`` attribute if one is not already set.
+
+        The id is ``"el-"`` followed by the first 6 hex characters of a
+        UUID4. Called automatically on construction when the
+        ``NITRO_UI_GENERATE_IDS`` environment variable is set.
+        """
         if "id" not in self._attributes:
             self._attributes["id"] = f"el-{str(uuid.uuid4())[:6]}"
 
     def clone(self) -> "HTMLElement":
-        """Clones the current tag."""
+        """Return a deep copy of this element and its entire subtree."""
         return copy.deepcopy(self)
 
     def replace_child(self, old_index: int, new_child: "HTMLElement") -> None:
-        """Replaces a existing child element with a new child element."""
+        """Swap a child at the given index with a new element.
+
+        Args:
+            old_index: Position of the child to replace.
+            new_child: Replacement element.
+
+        Raises:
+            ValueError: If ``new_child`` is not an ``HTMLElement``.
+            IndexError: If ``old_index`` is out of range.
+        """
         if not isinstance(new_child, HTMLElement):
             raise ValueError(
                 f"new_child must be an HTMLElement, got {type(new_child).__name__}"
@@ -604,18 +734,22 @@ def find_by_attribute(
         attr_value: Any,
         max_depth: int = DEFAULT_MAX_DEPTH,
     ) -> Union["HTMLElement", None]:
-        """Finds a child by an attribute.
+        """Return the first descendant (or self) whose attribute matches.
+
+        Performs a depth-first search through the subtree; the current
+        element itself is checked before its children.
 
         Args:
-            attr_name: The attribute name to search for
-            attr_value: The attribute value to match
-            max_depth: Maximum recursion depth (default 1000) to prevent stack overflow
+            attr_name: Attribute name to look up on each visited element.
+            attr_value: Value to compare against; must match exactly.
+            max_depth: Traversal cutoff (default 1000) guarding against
+                circular references.
 
         Returns:
-            The matching element or None if not found
+            The first matching element, or ``None`` if no match is found.
 
         Raises:
-            RecursionError: If max_depth is exceeded
+            RecursionError: If ``max_depth`` is exceeded.
         """
 
         def _find(
@@ -639,33 +773,52 @@ def _find(
         return _find(self)
 
     def get_attributes(self, *keys: str) -> dict:
-        """Returns the attributes of the current tag."""
+        """Return a copy of attributes, optionally restricted to given keys.
+
+        Args:
+            *keys: If provided, the returned dict is limited to these keys;
+                missing keys map to ``None``. If omitted, all attributes
+                are returned.
+
+        Returns:
+            A new dict; mutating it does not affect the element.
+        """
         if keys:
             return {key: self._attributes.get(key) for key in keys}
         return self._attributes.copy()
 
     def count_children(self) -> int:
-        """Returns the number of children in the current tag."""
+        """Return the number of direct children (not including text content)."""
         return len(self._children)
 
     def on_load(self) -> None:
-        """Callback called when the tag is loaded."""
+        """Hook called at the end of ``__init__``. Override for custom setup."""
         pass
 
     def on_before_render(self) -> None:
-        """Callback called before the tag is rendered."""
+        """Hook called immediately before this element renders itself.
+
+        Override to mutate the tree right before serialization. Called by
+        ``render()`` on each invocation, including nested child renders.
+        """
         pass
 
     def on_after_render(self) -> None:
-        """Callback called after the tag is rendered."""
+        """Hook called immediately after this element finishes rendering."""
         pass
 
     def on_unload(self) -> None:
-        """Callback called when the tag is unloaded."""
+        """Hook called from ``__del__``. Do not rely on this for cleanup.
+
+        Python's garbage collector may skip ``__del__`` for objects
+        participating in reference cycles. Use explicit cleanup or context
+        managers for anything load-bearing.
+        """
         pass
 
     @property
     def tag(self) -> str:
+        """The HTML tag name (e.g. ``"div"``, ``"span"``)."""
         return self._tag
 
     @tag.setter
@@ -674,6 +827,11 @@ def tag(self, value: str) -> None:
 
     @property
     def children(self) -> List["HTMLElement"]:
+        """A shallow copy of the list of child elements.
+
+        The returned list can be mutated without affecting this element.
+        Assigning to this property replaces the internal child list.
+        """
         return list(self._children)
 
     @children.setter
@@ -682,6 +840,7 @@ def children(self, value: List["HTMLElement"]) -> None:
 
     @property
     def text(self) -> str:
+        """Text content of this element (already-joined, unescaped source)."""
         return self._text
 
     @text.setter
@@ -690,6 +849,7 @@ def text(self, value: str) -> None:
 
     @property
     def attributes(self) -> dict:
+        """Live dict of attributes. Mutation invalidates the styles cache on assign."""
         return self._attributes
 
     @attributes.setter
@@ -699,6 +859,7 @@ def attributes(self, value: dict) -> None:
 
     @property
     def self_closing(self) -> bool:
+        """Whether this element renders as a void/self-closing tag."""
         return self._self_closing
 
     @self_closing.setter
@@ -754,19 +915,28 @@ def render(
         _indent: int = 0,
         max_depth: int = DEFAULT_MAX_DEPTH,
     ) -> str:
-        """
-        Renders the HTML element and its children to a string.
+        """Serialize this element and its subtree to an HTML string.
+
+        Attribute values and text content are HTML-escaped. The opening
+        tag, attributes, children, and closing tag are emitted in order;
+        self-closing elements emit ``<tag />`` with no children.
 
         Args:
-            pretty: If True, renders with indentation and newlines for readability
-            _indent: Internal parameter for tracking indentation level
-            max_depth: Maximum recursion depth (default 1000) to prevent stack overflow
+            pretty: If ``True``, insert indentation and newlines for
+                human-readable output. Defaults to compact output.
+            max_depth: Traversal cutoff (default 1000) guarding against
+                circular references in the tree.
 
         Returns:
-            String representation of the HTML element
+            HTML representation of this element.
 
         Raises:
-            RecursionError: If max_depth is exceeded (likely circular reference)
+            RecursionError: If ``max_depth`` is exceeded - usually a sign
+                of a circular reference rather than legitimate depth.
+
+        Example:
+            >>> Div(Paragraph("Hi"), class_name="card").render()
+            '<div class="card"><p>Hi</p></div>'
         """
         if _indent > max_depth:
             raise RecursionError(
@@ -829,17 +999,21 @@ def to_dict(
         _depth: int = 0,
         max_depth: int = DEFAULT_MAX_DEPTH,
     ) -> dict:
-        """Serialize the element to a dictionary.
+        """Serialize this element and its subtree to a plain dict.
+
+        The returned dict has keys ``tag``, ``self_closing``,
+        ``attributes``, ``text``, and ``children`` (recursively). It is
+        JSON-safe and round-trips via ``from_dict()``.
 
         Args:
-            _depth: Internal parameter for tracking recursion depth
-            max_depth: Maximum recursion depth (default 1000)
+            max_depth: Traversal cutoff (default 1000) guarding against
+                circular references.
 
         Returns:
-            Dictionary representation of the element
+            Dict representation of the element.
 
         Raises:
-            RecursionError: If max_depth is exceeded
+            RecursionError: If ``max_depth`` is exceeded.
         """
         if _depth > max_depth:
             raise RecursionError(
@@ -858,14 +1032,14 @@ def to_dict(
         }
 
     def to_json(self, indent: Union[int, None] = None) -> str:
-        """
-        Serializes the element and its children to a JSON string.
+        """Serialize this element and its subtree to a JSON string.
 
         Args:
-            indent: Number of spaces for JSON indentation (None for compact output)
+            indent: Spaces for pretty-printed JSON, or ``None`` for compact
+                single-line output.
 
         Returns:
-            JSON string representation of the element
+            JSON representation; pair with ``from_json()`` to round-trip.
         """
         return json.dumps(self.to_dict(), indent=indent)
 
@@ -876,20 +1050,23 @@ def from_dict(
         _depth: int = 0,
         max_depth: int = DEFAULT_MAX_DEPTH,
     ) -> "HTMLElement":
-        """
-        Reconstructs an HTMLElement from a dictionary.
+        """Reconstruct an element tree from a ``to_dict()`` result.
+
+        Uses the tag registry populated by the tag factory to instantiate
+        the most specific subclass for each tag, so ``Fragment``,
+        ``Table``, ``Form``, etc. round-trip as their real types.
 
         Args:
-            data: Dictionary containing element data (from to_dict())
-            _depth: Internal parameter for tracking recursion depth
-            max_depth: Maximum recursion depth (default 1000)
+            data: Dict produced by ``to_dict()``.
+            max_depth: Traversal cutoff (default 1000).
 
         Returns:
-            Reconstructed HTMLElement instance
+            Reconstructed ``HTMLElement`` (or subclass matching ``tag``).
 
         Raises:
-            ValueError: If input data is invalid
-            RecursionError: If max_depth is exceeded
+            ValueError: If ``data`` is not a dict, is missing ``tag``, or
+                has a field with the wrong type.
+            RecursionError: If ``max_depth`` is exceeded.
         """
         if not isinstance(data, dict):
             raise ValueError("Input must be a dictionary")
@@ -966,14 +1143,17 @@ def from_dict(
 
     @classmethod
     def from_json(cls, json_str: str) -> "HTMLElement":
-        """
-        Reconstructs an HTMLElement from a JSON string.
+        """Reconstruct an element tree from a ``to_json()`` result.
 
         Args:
-            json_str: JSON string representation (from to_json())
+            json_str: JSON previously produced by ``to_json()``.
 
         Returns:
-            Reconstructed HTMLElement instance
+            Reconstructed ``HTMLElement`` (or registered subclass).
+
+        Raises:
+            ValueError: If the string is not valid JSON or the decoded
+                payload is not a valid element dict.
         """
         try:
             data = json.loads(json_str)
diff --git a/src/nitro_ui/core/parser.py b/src/nitro_ui/core/parser.py
index f274ccd..51af9d3 100644
--- a/src/nitro_ui/core/parser.py
+++ b/src/nitro_ui/core/parser.py
@@ -195,28 +195,32 @@ def parse_fragment(self, html_string: str) -> List[HTMLElement]:
 def from_html(
     html_string: str, fragment: bool = False
 ) -> Union[HTMLElement, List[HTMLElement], None]:
-    """Parse HTML string and convert to NitroUI element(s).
+    """Parse an HTML string into a NitroUI element tree.
+
+    Uses the standard library's ``html.parser`` under the hood. Class
+    attributes are mapped to ``class_name``; SVG camelCase attributes
+    (``viewBox`` etc.) are preserved. Whitespace inside ``<pre>``,
+    ``<code>``, ``<textarea>``, ``<script>``, and ``<style>`` is kept
+    verbatim; elsewhere it is stripped.
 
     Args:
-        html_string: Raw HTML string to parse
-        fragment: If True, returns list of elements (for HTML fragments)
-                 If False, returns single root element (default)
+        html_string: Raw HTML source.
+        fragment: If ``True``, return a list with every root-level
+            element (useful for snippets). If ``False``, return only the
+            first root element, or ``None`` for an empty input.
 
     Returns:
-        HTMLElement if fragment=False, List[HTMLElement] if fragment=True
+        A single ``HTMLElement`` when ``fragment=False`` (or ``None`` if
+        nothing was parsed), otherwise a list of elements.
+
+    Raises:
+        TypeError: If ``html_string`` is not a string.
 
     Example:
-        >>> from nitro_ui.core.parser import from_html
-        >>>
-        >>> # Parse single element
-        >>> element = from_html('<div class="container"><h1>Hello</h1></div>')
-        >>> print(element.render())
-        <div class="container"><h1>Hello</h1></div>
-        >>>
-        >>> # Parse fragment (multiple root elements)
-        >>> elements = from_html('<h1>Title</h1><p>Content</p>', fragment=True)
-        >>> for el in elements:
-        ...     print(el.render())
+        >>> from_html('<div class="container"><h1>Hello</h1></div>').render()
+        '<div class="container"><h1>Hello</h1></div>'
+        >>> [el.render() for el in from_html('<h1>A</h1><p>B</p>', fragment=True)]
+        ['<h1>A</h1>', '<p>B</p>']
     """
     if not isinstance(html_string, str):
         raise TypeError(
diff --git a/src/nitro_ui/core/partial.py b/src/nitro_ui/core/partial.py
index 1614c8a..004a22f 100644
--- a/src/nitro_ui/core/partial.py
+++ b/src/nitro_ui/core/partial.py
@@ -59,7 +59,11 @@ def render(
         return result
 
     def to_dict(self) -> dict:
-        """Serializes the Partial to a dictionary."""
+        """Return a dict with ``type="partial"`` plus the source marker.
+
+        Either the inline ``html`` string or the ``file`` path is stored
+        - whichever was provided at construction time.
+        """
         result = {"type": "partial"}
         if self._html is not None:
             result["html"] = self._html
@@ -68,21 +72,30 @@ def to_dict(self) -> dict:
         return result
 
     def to_json(self, indent: int = None) -> str:
-        """Serializes the Partial to a JSON string."""
+        """Serialize this Partial to a JSON string.
+
+        Args:
+            indent: Spaces for pretty-printed JSON, or ``None`` for
+                compact output.
+        """
         import json
 
         return json.dumps(self.to_dict(), indent=indent)
 
     @classmethod
     def from_dict(cls, data: dict) -> "Partial":
-        """Reconstructs a Partial from a dictionary."""
+        """Reconstruct a ``Partial`` from a ``to_dict()`` result.
+
+        Raises:
+            ValueError: If ``data["type"]`` is not ``"partial"``.
+        """
         if data.get("type") != "partial":
             raise ValueError("Not a Partial element")
         return cls(html=data.get("html"), file=data.get("file"))
 
     @classmethod
     def from_json(cls, json_str: str) -> "Partial":
-        """Reconstructs a Partial from a JSON string."""
+        """Reconstruct a ``Partial`` from a ``to_json()`` result."""
         import json
 
         data = json.loads(json_str)
diff --git a/src/nitro_ui/core/slot.py b/src/nitro_ui/core/slot.py
index 0c1f31d..e3f209b 100644
--- a/src/nitro_ui/core/slot.py
+++ b/src/nitro_ui/core/slot.py
@@ -54,6 +54,9 @@ def __repr__(self) -> str:
     def render(
         self, pretty: bool = False, _indent: int = 0, max_depth: int = 1000
     ) -> str:
-        """Slots should never render directly - they get replaced by Component."""
-        # Return empty string if somehow rendered directly
+        """Return an empty string - ``Component`` replaces slots before render.
+
+        This safety net keeps output clean if a ``Slot`` escapes the
+        component machinery. It should never be called during normal use.
+        """
         return ""
diff --git a/src/nitro_ui/forms/field.py b/src/nitro_ui/forms/field.py
index 9887005..5b3a4d6 100644
--- a/src/nitro_ui/forms/field.py
+++ b/src/nitro_ui/forms/field.py
@@ -60,21 +60,27 @@ def _filter_none(**kwargs) -> Dict[str, Any]:
 
 
 class Field:
-    """Static methods for generating HTML5 form fields with validation attributes.
+    """Factory of static methods that emit common HTML5 form inputs.
 
-    All methods return standard NitroUI elements that can be composed with
-    other elements. Use the `label` parameter to add a label, and `wrapper`
-    to wrap the field in a div for styling.
+    Every method returns a regular NitroUI ``HTMLElement`` so results
+    compose with the rest of the library. Two optional knobs are shared
+    across most methods:
 
-    Example:
-        from nitro_ui import Form, Button
-        from nitro_ui.forms import Field
+    - ``label``: when provided, wraps the input with a ``<label>``.
+      Checkboxes and radios are special-cased so the label behaves
+      correctly for their semantics.
+    - ``wrapper``: when provided, nests the field inside a ``<div>``.
+      Pass a string to use it as the wrapper's class, or a dict to
+      forward arbitrary attributes.
 
-        form = Form(
-            Field.email("email", label="Email", required=True),
-            Field.password("password", label="Password", min_length=8),
-            Button("Log In", type="submit")
-        )
+    Example:
+        >>> from nitro_ui import Form, Button
+        >>> from nitro_ui.forms import Field
+        >>> form = Form(
+        ...     Field.email("email", label="Email", required=True),
+        ...     Field.password("password", label="Password", min_length=8),
+        ...     Button("Log In", type="submit"),
+        ... )
     """
 
     # =========================================================================
@@ -95,20 +101,26 @@ def text(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a text input field.
+        """Build a single-line ``<input type="text">`` with validation attrs.
 
         Args:
-            name: Field name and default id
-            label: Optional label text
-            required: Whether the field is required
-            min_length: Minimum character length
-            max_length: Maximum character length
-            pattern: Regex pattern for validation
-            placeholder: Placeholder text
-            value: Default value
-            wrapper: Wrapper div class name or attributes dict
-            id: Custom id (defaults to name)
-            **attrs: Additional HTML attributes
+            name: Form field name; also used as the default ``id``.
+            label: Optional visible ``<label>`` text.
+            required: Emit the HTML ``required`` attribute.
+            min_length: Minimum character count (``minlength``).
+            max_length: Maximum character count (``maxlength``).
+            pattern: JS regex source for client-side validation.
+            placeholder: Placeholder text shown when empty.
+            value: Initial value of the input.
+            wrapper: ``<div>`` wrapper - a CSS class string or an
+                attribute dict.
+            id: Override the default id (defaults to ``name``).
+            **attrs: Extra attributes passed through to the ``<input>``.
+
+        Returns:
+            An ``<input>``, a ``Fragment(<label>, <input>)``, or the
+            pair wrapped in a ``<div>`` - depending on which optional
+            arguments were supplied.
         """
         field_id = id or name
         input_attrs = _filter_none(
@@ -137,7 +149,12 @@ def email(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create an email input field."""
+        """Build an ``<input type="email">`` with browser-side format validation.
+
+        Same shared options as :meth:`text` (``label``, ``wrapper``,
+        ``id``, ``**attrs``). Browsers validate the value against their
+        internal email grammar when ``required`` is set.
+        """
         field_id = id or name
         input_attrs = _filter_none(
             type="email",
@@ -163,7 +180,12 @@ def password(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a password input field."""
+        """Build an ``<input type="password">`` with optional length constraints.
+
+        Has no ``value`` parameter - passwords should not be
+        round-tripped. Use ``min_length`` / ``max_length`` for strength
+        hints. Same shared options as :meth:`text`.
+        """
         field_id = id or name
         input_attrs = _filter_none(
             type="password",
@@ -189,7 +211,11 @@ def url(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a URL input field."""
+        """Build an ``<input type="url">`` with browser-side URL validation.
+
+        Same shared options as :meth:`text`. Browsers validate against a
+        basic absolute-URL grammar when ``required`` is set.
+        """
         field_id = id or name
         input_attrs = _filter_none(
             type="url",
@@ -215,7 +241,12 @@ def tel(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a telephone input field."""
+        """Build an ``<input type="tel">`` for phone-number entry.
+
+        The ``tel`` input type enables mobile keyboards but browsers do
+        no format validation - supply a ``pattern`` for client-side
+        checks. Same shared options as :meth:`text`.
+        """
         field_id = id or name
         input_attrs = _filter_none(
             type="tel",
@@ -241,7 +272,11 @@ def search(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a search input field."""
+        """Build an ``<input type="search">`` with browser-provided clear affordance.
+
+        Same shared options as :meth:`text`. Browsers typically render a
+        built-in "clear" control and inline search decorations.
+        """
         field_id = id or name
         input_attrs = _filter_none(
             type="search",
@@ -270,7 +305,12 @@ def textarea(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a textarea field."""
+        """Build a multi-line ``<textarea>`` input.
+
+        Any ``value`` is inserted as the textarea's text content (not an
+        attribute, per the HTML spec). Supports ``rows`` / ``cols`` sizing
+        and ``min_length`` / ``max_length`` validation.
+        """
         field_id = id or name
         textarea_attrs = _filter_none(
             id=field_id,
@@ -307,7 +347,12 @@ def number(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a number input field."""
+        """Build an ``<input type="number">`` for numeric entry.
+
+        Use ``min`` / ``max`` / ``step`` to constrain the allowed values.
+        ``step="any"`` permits arbitrary decimals. Same shared options
+        as :meth:`text`.
+        """
         field_id = id or name
         input_attrs = _filter_none(
             type="number",
@@ -335,7 +380,12 @@ def range(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a range slider input field."""
+        """Build an ``<input type="range">`` slider with a bounded numeric range.
+
+        Defaults to ``min=0`` and ``max=100``. The slider value is
+        always within the inclusive ``[min, max]`` range; ``step``
+        controls the snap increment.
+        """
         field_id = id or name
         input_attrs = _filter_none(
             type="range",
@@ -366,10 +416,15 @@ def date(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a date input field.
+        """Build an ``<input type="date">`` picker constrained to ``YYYY-MM-DD`` dates.
+
+        Browsers render a native date picker. Same shared options as
+        :meth:`text`.
 
         Args:
-            min/max/value: Date strings in YYYY-MM-DD format
+            min: Earliest selectable date as ``YYYY-MM-DD``.
+            max: Latest selectable date as ``YYYY-MM-DD``.
+            value: Initial date as ``YYYY-MM-DD``.
         """
         field_id = id or name
         input_attrs = _filter_none(
@@ -397,10 +452,15 @@ def time(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a time input field.
+        """Build an ``<input type="time">`` picker constrained to ``HH:MM`` times.
+
+        Browsers render a native time picker. Same shared options as
+        :meth:`text`.
 
         Args:
-            min/max/value: Time strings in HH:MM format
+            min: Earliest selectable time as ``HH:MM``.
+            max: Latest selectable time as ``HH:MM``.
+            value: Initial time as ``HH:MM``.
         """
         field_id = id or name
         input_attrs = _filter_none(
@@ -428,10 +488,15 @@ def datetime_local(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a datetime-local input field.
+        """Build an ``<input type="datetime-local">`` picker for local datetimes.
+
+        The value is timezone-naive; browsers submit it as
+        ``YYYY-MM-DDTHH:MM``. Same shared options as :meth:`text`.
 
         Args:
-            min/max/value: Datetime strings in YYYY-MM-DDTHH:MM format
+            min: Earliest selectable value as ``YYYY-MM-DDTHH:MM``.
+            max: Latest selectable value as ``YYYY-MM-DDTHH:MM``.
+            value: Initial value as ``YYYY-MM-DDTHH:MM``.
         """
         field_id = id or name
         input_attrs = _filter_none(
@@ -462,19 +527,26 @@ def select(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a select dropdown field.
+        """Build a ``<select>`` dropdown populated from a flexible options list.
+
+        Options accept three shapes, in order of flexibility:
+
+        - ``str``: ``"USA"`` - value and label are identical.
+        - ``tuple``: ``("us", "United States")`` - ``(value, label)``.
+        - ``dict``: ``{"value": "us", "label": "United States",
+          "disabled": True}`` - arbitrary extra keys become
+          ``<option>`` attributes.
 
         Args:
-            name: Field name
-            options: List of options - can be:
-                - strings: ["USA", "Canada"] - value and label are the same
-                - tuples: [("us", "United States")] - (value, label)
-                - dicts: [{"value": "us", "label": "United States", "disabled": True}]
-            label: Optional label text
-            required: Whether selection is required
-            value: Pre-selected value
-            wrapper: Wrapper div class name or attributes dict
-            id: Custom id (defaults to name)
+            name: Form field name; also used as the default id.
+            options: Iterable of option descriptors (see above).
+            label: Optional ``<label>`` text.
+            required: Emit the HTML ``required`` attribute.
+            value: Pre-select the option whose value matches (compared
+                as strings).
+            wrapper: ``<div>`` wrapper - class string or attribute dict.
+            id: Override the default id (defaults to ``name``).
+            **attrs: Extra attributes passed to the ``<select>``.
         """
         field_id = id or name
 
@@ -520,18 +592,23 @@ def checkbox(
         required: bool = False,
         **attrs,
     ) -> HTMLElement:
-        """Create a checkbox field.
+        """Build an ``<input type="checkbox">``, with the label wrapping the input.
 
-        For checkboxes, the label wraps the input for better UX.
+        Unlike other field factories, the label here wraps the checkbox
+        - clicking the label text toggles the state, which is the
+        conventional accessible layout.
 
         Args:
-            name: Field name
-            label: Label text (wraps the checkbox)
-            checked: Whether the checkbox is pre-checked
-            value: Value sent when checked (default "on")
-            wrapper: Wrapper div class name or attributes dict
-            id: Custom id (defaults to name)
-            required: Whether the checkbox must be checked
+            name: Form field name; also used as the default id.
+            label: Label text. When provided, wraps ``<input>`` and a
+                ``<span>`` containing the text.
+            checked: Emit the ``checked`` attribute.
+            value: Value submitted when the box is checked. Defaults
+                to ``"on"``, matching browser behaviour.
+            wrapper: ``<div>`` wrapper - class string or attribute dict.
+            id: Override the default id (defaults to ``name``).
+            required: Emit the ``required`` attribute - the box must
+                be ticked for the form to submit.
         """
         field_id = id or name
         input_attrs = _filter_none(
@@ -575,17 +652,23 @@ def radio(
         wrapper: Optional[Union[str, Dict[str, Any]]] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a radio button group.
+        """Build a radio-button group wrapped in an accessible ``<fieldset>``.
 
-        Radio buttons are wrapped in a fieldset with legend for accessibility.
+        Every option produces an ``<input type="radio">`` that shares
+        ``name`` with its siblings; a ``<legend>`` carries the group
+        label. Only the first option receives the ``required`` attribute
+        - that is sufficient for the entire group.
 
         Args:
-            name: Field name (shared by all radio buttons)
-            options: List of options - tuples or dicts like select()
-            label: Legend text for the fieldset
-            required: Whether selection is required
-            value: Pre-selected value
-            wrapper: Wrapper div class name or attributes dict
+            name: Shared form field name for the group.
+            options: Iterable of ``(value, label)`` tuples or option
+                dicts with ``value``/``label``/extra keys, mirroring
+                :meth:`select`.
+            label: Text for the group's ``<legend>``.
+            required: Require a selection before the form submits.
+            value: Value of the option to pre-check (compared as strings).
+            wrapper: ``<div>`` wrapper - class string or attribute dict.
+            **attrs: Extra attributes applied to every ``<input>``.
         """
         # Build radio button elements
         radio_elements = []
@@ -648,16 +731,17 @@ def file(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a file upload field.
+        """Build an ``<input type="file">`` for attaching files from the client.
 
         Args:
-            name: Field name
-            label: Optional label text
-            required: Whether file selection is required
-            accept: Accepted file types (e.g., "image/*", ".pdf,.doc")
-            multiple: Allow multiple file selection
-            wrapper: Wrapper div class name or attributes dict
-            id: Custom id (defaults to name)
+            name: Form field name; also used as the default id.
+            label: Optional ``<label>`` text.
+            required: Emit the ``required`` attribute.
+            accept: Filter the native picker by MIME types or
+                extensions (e.g. ``"image/*"``, ``".pdf,.doc"``).
+            multiple: Allow selecting more than one file at once.
+            wrapper: ``<div>`` wrapper - class string or attribute dict.
+            id: Override the default id (defaults to ``name``).
         """
         field_id = id or name
         input_attrs = _filter_none(
@@ -674,11 +758,15 @@ def file(
 
     @staticmethod
     def hidden(name: str, value: str, **attrs) -> HTMLElement:
-        """Create a hidden input field.
+        """Build an ``<input type="hidden">`` for carrying state through a form.
+
+        Always returns a bare ``<input>`` - no label, no wrapper - since
+        hidden inputs are not user-visible.
 
         Args:
-            name: Field name
-            value: Hidden value
+            name: Form field name.
+            value: Value submitted with the form.
+            **attrs: Extra attributes passed through to the ``<input>``.
         """
         return Input(type="hidden", name=name, value=value, **attrs)
 
@@ -691,14 +779,17 @@ def color(
         id: Optional[str] = None,
         **attrs,
     ) -> HTMLElement:
-        """Create a color picker field.
+        """Build an ``<input type="color">`` color picker.
+
+        Browsers submit colors as ``#RRGGBB`` lowercase hex; the picker
+        UI is browser-native.
 
         Args:
-            name: Field name
-            label: Optional label text
-            value: Default color in #RRGGBB format
-            wrapper: Wrapper div class name or attributes dict
-            id: Custom id (defaults to name)
+            name: Form field name; also used as the default id.
+            label: Optional ``<label>`` text.
+            value: Initial color as ``#RRGGBB`` hex.
+            wrapper: ``<div>`` wrapper - class string or attribute dict.
+            id: Override the default id (defaults to ``name``).
         """
         field_id = id or name
         input_attrs = _filter_none(
diff --git a/src/nitro_ui/styles/style.py b/src/nitro_ui/styles/style.py
index 744d550..acc2efa 100644
--- a/src/nitro_ui/styles/style.py
+++ b/src/nitro_ui/styles/style.py
@@ -7,40 +7,39 @@
 
 
 class CSSStyle:
-    """
-    Represents CSS styles with support for pseudo-selectors and responsive breakpoints.
-
-    Usage:
-        # Basic styles
-        style = CSSStyle(
-            background_color="#007bff",
-            color="white",
-            padding="10px 20px"
-        )
-
-        # With pseudo-selectors
-        style = CSSStyle(
-            background_color="#007bff",
-            _hover=CSSStyle(background_color="#0056b3"),
-            _active=CSSStyle(transform="scale(0.98)")
-        )
-
-        # With responsive breakpoints
-        style = CSSStyle(
-            padding="10px",
-            _sm=CSSStyle(padding="15px"),
-            _md=CSSStyle(padding="20px")
-        )
+    """Declarative CSS style with pseudo-selector and breakpoint support.
+
+    Instances capture a set of base CSS declarations plus nested
+    ``CSSStyle`` objects for pseudo-selectors (``:hover``, ``:active``,
+    ...) and responsive breakpoints (``sm``, ``md``, ``lg``, ...).
+    Property names are written in snake_case; they are converted to
+    kebab-case at emit time.
+
+    Example:
+        >>> style = CSSStyle(
+        ...     background_color="#007bff",
+        ...     color="white",
+        ...     _hover=CSSStyle(background_color="#0056b3"),
+        ...     _md=CSSStyle(padding="20px"),
+        ... )
+        >>> style.to_inline()
+        'background-color: #007bff; color: white'
     """
 
     def __init__(self, **kwargs):
-        """
-        Initialize a CSSStyle object.
+        """Create a CSSStyle from keyword arguments.
 
         Args:
-            **kwargs: CSS properties as keyword arguments. Use underscores for hyphens.
-                     Pseudo-selectors start with underscore (e.g., _hover, _active)
-                     Breakpoints start with underscore (e.g., _sm, _md, _lg)
+            **kwargs: CSS declarations as ``property=value`` pairs.
+                Underscores in names become hyphens
+                (``background_color`` -> ``background-color``). Values
+                starting with an underscore and assigned a ``CSSStyle``
+                are routed to the pseudo-selector or breakpoint maps:
+                ``_hover``, ``_active``, ``_focus``, ``_visited``,
+                ``_link``, ``_first_child``, ``_last_child``,
+                ``_nth_child``, ``_before``, ``_after``, plus
+                breakpoints ``_xs``, ``_sm``, ``_md``, ``_lg``, ``_xl``,
+                ``_2xl``.
         """
         self._styles: Dict[str, str] = {}
         self._pseudo: Dict[str, "CSSStyle"] = {}
@@ -84,16 +83,17 @@ def _to_css_prop(self, prop: str) -> str:
         return prop.replace("_", "-")
 
     def merge(self, other: "CSSStyle") -> "CSSStyle":
-        """
-        Merge another CSSStyle object into this one, returning a new CSSStyle.
-        The other style's properties will override this one's.
-        Pseudo-selectors and breakpoints are deep-merged at the property level.
+        """Combine another style into a new ``CSSStyle`` without mutating either.
+
+        Values from ``other`` win on conflict. Pseudo-selectors and
+        breakpoints are deep-merged recursively, so an ``_hover`` on
+        either side survives.
 
         Args:
-            other: Another CSSStyle object to merge
+            other: Style whose declarations overlay this one.
 
         Returns:
-            New CSSStyle object with merged properties
+            A new ``CSSStyle`` with the merged content.
         """
         merged = CSSStyle()
         merged._styles = {**self._styles, **other._styles}
@@ -124,16 +124,19 @@ def merge(self, other: "CSSStyle") -> "CSSStyle":
         return merged
 
     def to_inline(self) -> str:
-        """
-        Generate inline style string (for style="..." attribute).
-        Note: This only includes base styles, not pseudo-selectors or breakpoints.
-        Values are validated against CSS injection patterns.
+        """Render the base declarations as a single ``style`` attribute value.
+
+        Only the base declarations are emitted - pseudo-selectors and
+        breakpoints cannot be expressed inline and require a stylesheet.
+        Values are validated against the same injection patterns
+        enforced by ``HTMLElement.add_style``.
 
         Returns:
-            CSS string suitable for inline styles
+            A string like ``"color: red; padding: 10px"``, or an empty
+            string if no base declarations are set.
 
         Raises:
-            ValueError: If any CSS value contains dangerous content
+            ValueError: If any value contains potentially dangerous content.
         """
         if not self._styles:
             return ""
@@ -147,11 +150,13 @@ def to_inline(self) -> str:
         return "; ".join(f"{k}: {v}" for k, v in self._styles.items())
 
     def to_dict(self) -> Dict[str, Any]:
-        """
-        Serialize to JSON-compatible dictionary.
+        """Serialize this style (including nested pseudo/breakpoint maps) to a dict.
+
+        The output is JSON-safe and round-trips via ``from_dict()``.
 
         Returns:
-            Dictionary representation of the style
+            A dict with keys ``styles``, optionally ``pseudo`` and
+            ``breakpoints`` holding nested ``CSSStyle.to_dict()`` output.
         """
         result: Dict[str, Any] = {"styles": self._styles.copy()}
 
@@ -167,14 +172,13 @@ def to_dict(self) -> Dict[str, Any]:
 
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "CSSStyle":
-        """
-        Deserialize from dictionary.
+        """Reconstruct a ``CSSStyle`` from a ``to_dict()`` result.
 
         Args:
-            data: Dictionary representation from to_dict()
+            data: Dict previously produced by ``to_dict()``.
 
         Returns:
-            New CSSStyle object
+            A new ``CSSStyle`` equivalent to the serialized one.
         """
         style = cls()
         style._styles = dict(data.get("styles", {}))
@@ -190,34 +194,32 @@ def from_dict(cls, data: Dict[str, Any]) -> "CSSStyle":
         return style
 
     def has_pseudo_or_breakpoints(self) -> bool:
-        """
-        Check if this style has pseudo-selectors or breakpoints.
-        Useful for deciding whether to extract to external stylesheet.
+        """Return ``True`` if this style carries any pseudo-selector or breakpoint.
 
-        Returns:
-            True if style has pseudo-selectors or breakpoints
+        Inline ``style="..."`` can't express pseudo-selectors or media
+        queries, so this is a useful signal for deciding whether the
+        style must be registered on a ``StyleSheet``.
         """
         return bool(self._pseudo or self._breakpoints)
 
     def is_complex(self, threshold: int = 3) -> bool:
-        """
-        Check if this style is complex (has many properties).
-        Useful for deciding whether to extract to external stylesheet.
+        """Return ``True`` when the base declaration count exceeds a threshold.
 
-        Args:
-            threshold: Number of properties to consider complex
+        Useful alongside ``has_pseudo_or_breakpoints`` to decide whether
+        a given style is better off in an external stylesheet.
 
-        Returns:
-            True if style has more properties than threshold
+        Args:
+            threshold: Maximum number of declarations considered simple;
+                the style is "complex" when it has strictly more.
         """
         return len(self._styles) > threshold
 
     def __repr__(self) -> str:
-        """String representation for debugging."""
+        """Return a debug representation showing the inline form."""
         return f"CSSStyle({self.to_inline()})"
 
     def __eq__(self, other: object) -> bool:
-        """Check equality with another CSSStyle."""
+        """Return ``True`` if both styles have identical base, pseudo, and breakpoint maps."""
         if not isinstance(other, CSSStyle):
             return False
         return (
@@ -227,7 +229,7 @@ def __eq__(self, other: object) -> bool:
         )
 
     def __hash__(self) -> int:
-        """Make CSSStyle hashable for use in dictionaries."""
+        """Return a stable hash based on declarations and pseudo/breakpoint keys."""
         styles_tuple = tuple(sorted(self._styles.items()))
         # Include pseudo and breakpoint keys in hash for better distribution
         pseudo_keys = tuple(sorted(self._pseudo.keys()))
diff --git a/src/nitro_ui/styles/stylesheet.py b/src/nitro_ui/styles/stylesheet.py
index 1d73eaa..91c6040 100644
--- a/src/nitro_ui/styles/stylesheet.py
+++ b/src/nitro_ui/styles/stylesheet.py
@@ -60,34 +60,27 @@ def _sanitize_css_value(value: str) -> str:
 
 
 class StyleSheet:
-    """
-    Manages CSS classes and generates <style> tag content.
-
-    Usage:
-        # Create stylesheet
-        stylesheet = StyleSheet()
-
-        # Register styles
-        btn_class = stylesheet.register("btn-primary", CSSStyle(
-            background_color="#007bff",
-            color="white",
-            padding="10px 20px",
-            _hover=CSSStyle(background_color="#0056b3")
-        ))
-
-        # Use in HTML
-        button = Button("Click", class_name=btn_class)
-
-        # Render CSS
-        css_output = stylesheet.render()
+    """Registry of named CSS classes that renders to a ``<style>`` block.
+
+    Attach ``CSSStyle`` objects under class names (or let the registry
+    auto-name them), then emit the full stylesheet - including any theme
+    CSS variables - with ``render()`` or ``to_style_tag()``. Responsive
+    breakpoints stored on styles are rendered as ``@media`` queries
+    using this sheet's breakpoint values.
+
+    Example:
+        >>> sheet = StyleSheet()
+        >>> btn = sheet.register("btn-primary", CSSStyle(color="white"))
+        >>> Button("Click", class_name=btn)  # doctest: +SKIP
+        >>> sheet.render()  # doctest: +SKIP
     """
 
     def __init__(self, theme: Optional["Theme"] = None):
-        """
-        Initialize StyleSheet.
+        """Create a new, empty stylesheet optionally tied to a theme.
 
         Args:
-            theme: Optional Theme object to include CSS variables
+            theme: Optional ``Theme`` whose CSS variables are emitted
+                inside a ``:root`` block when this sheet is rendered.
         """
         self.theme = theme
         self._classes: Dict[str, CSSStyle] = {}
@@ -106,18 +99,27 @@ def __init__(self, theme: Optional["Theme"] = None):
     def register(
         self, name: Optional[str] = None, style: Optional[CSSStyle] = None
     ) -> str:
-        """
-        Register a style as a CSS class.
+        """Store a style under a class name and return the name for use in HTML.
+
+        If ``name`` is omitted, an auto-name like ``"s-0"`` is generated.
+        User-supplied names are validated - BEM notation (``__``, ``--``)
+        is permitted but random punctuation is not.
 
         Args:
-            name: Optional class name. If not provided, auto-generates one.
-            style: CSSStyle object to register
+            name: Explicit class name, or ``None`` to auto-generate.
+            style: Style to register. An empty ``CSSStyle`` is used if
+                omitted - useful for reserving a name.
 
         Returns:
-            The class name (for use in class_name attribute)
+            The class name to pass to ``class_name=`` on an element.
 
         Raises:
-            ValueError: If the class name is invalid (contains dangerous characters)
+            ValueError: If ``name`` fails class-name validation.
+
+        Example:
+            >>> sheet = StyleSheet()
+            >>> sheet.register("btn", CSSStyle(color="white"))
+            'btn'
         """
         if style is None:
             style = CSSStyle()
@@ -147,17 +149,20 @@ def register_bem(
         modifier: Optional[str] = None,
         style: Optional[CSSStyle] = None,
     ) -> str:
-        """
-        Register a style using BEM naming convention.
+        """Register a style with a BEM-formatted class name.
+
+        Assembles ``block``, ``block__element``, or
+        ``block__element--modifier`` and delegates to ``register()``.
 
         Args:
-            block: Block name (e.g., "button")
-            element: Optional element name (e.g., "icon")
-            modifier: Optional modifier name (e.g., "primary")
-            style: CSSStyle object to register
+            block: Block name (e.g. ``"button"``).
+            element: Element name within the block (e.g. ``"icon"``).
+            modifier: Modifier applied to the block or element
+                (e.g. ``"primary"``).
+            style: Style to register against the generated name.
 
         Returns:
-            The BEM class name
+            The full BEM class name - e.g. ``"button__icon--primary"``.
         """
         # Build BEM class name
         class_name = block
@@ -171,38 +176,22 @@ def register_bem(
         return self.register(class_name, style)
 
     def get_style(self, name: str) -> Optional[CSSStyle]:
-        """
-        Get a registered style by class name.
-
-        Args:
-            name: Class name
-
-        Returns:
-            CSSStyle object or None if not found
-        """
+        """Return the style registered for a class name, or ``None`` if absent."""
         return self._classes.get(name)
 
     def has_class(self, name: str) -> bool:
-        """
-        Check if a class is registered.
-
-        Args:
-            name: Class name
-
-        Returns:
-            True if class exists
-        """
+        """Return ``True`` if a style is registered under this class name."""
         return name in self._classes
 
     def unregister(self, name: str) -> bool:
-        """
-        Remove a registered class.
+        """Remove a registered class and return whether it existed.
 
         Args:
-            name: Class name to remove
+            name: Class name to remove.
 
         Returns:
-            True if class was removed, False if not found
+            ``True`` if the class was present and removed, ``False``
+            if it was never registered.
         """
         if name in self._classes:
             del self._classes[name]
@@ -210,17 +199,19 @@ def unregister(self, name: str) -> bool:
         return False
 
     def clear(self) -> None:
-        """Remove all registered classes."""
+        """Drop every registered class and reset the auto-name counter."""
         self._classes.clear()
         self._counter = 0
 
     def set_breakpoint(self, name: str, value: str) -> None:
-        """
-        Set or update a breakpoint value.
+        """Override the ``min-width`` value used for a named breakpoint.
+
+        Affects the ``@media`` queries emitted by ``render()`` for any
+        styles that define responsive overrides.
 
         Args:
-            name: Breakpoint name (e.g., "sm", "md")
-            value: CSS value (e.g., "640px")
+            name: Breakpoint key (e.g. ``"sm"``, ``"md"``).
+            value: CSS length string (e.g. ``"640px"``).
         """
         self._breakpoint_values[name] = value
 
@@ -278,14 +269,23 @@ def _render_class_styles(
         return css_lines
 
     def render(self, pretty: bool = True) -> str:
-        """
-        Generate CSS output for all registered classes.
+        """Emit the full CSS text for every registered class.
+
+        Output order: ``:root`` block with theme variables (if a theme
+        was provided), then each class in registration order with its
+        base rules, pseudo-selectors, and breakpoint media queries.
+        Values are re-validated against injection patterns on render.
 
         Args:
-            pretty: If True, format with newlines and indentation
+            pretty: If ``True``, format with line breaks and indentation.
+                If ``False``, collapse into a single compact line -
+                suitable for embedding in an inline ``<style>``.
 
         Returns:
-            CSS string
+            CSS source string.
+
+        Raises:
+            ValueError: If any registered value contains dangerous content.
         """
         css_lines = []
 
@@ -313,14 +313,14 @@ def render(self, pretty: bool = True) -> str:
             return "".join(line.strip() for line in css_lines)
 
     def to_style_tag(self, pretty: bool = True) -> str:
-        """
-        Generate a complete <style> tag with all CSS.
+        """Return the rendered CSS wrapped in a ready-to-drop ``<style>`` tag.
 
         Args:
-            pretty: If True, format with newlines and indentation
+            pretty: Forwarded to ``render()``; controls whether the
+                inner CSS is pretty-printed or compact.
 
         Returns:
-            HTML <style> tag with CSS
+            A string starting with ``<style>`` and ending with ``</style>``.
         """
         css = self.render(pretty=pretty)
         if pretty:
@@ -329,29 +329,19 @@ def to_style_tag(self, pretty: bool = True) -> str:
             return f"<style>{css}</style>"
 
     def count_classes(self) -> int:
-        """
-        Get the number of registered classes.
-
-        Returns:
-            Number of classes
-        """
+        """Return the number of classes currently registered on this sheet."""
         return len(self._classes)
 
     def get_all_class_names(self) -> List[str]:
-        """
-        Get a list of all registered class names.
-
-        Returns:
-            List of class names
-        """
+        """Return a list of every registered class name, in insertion order."""
         return list(self._classes.keys())
 
     def to_dict(self) -> Dict:
-        """
-        Serialize stylesheet to dictionary.
+        """Serialize registered classes and breakpoint overrides to a dict.
 
-        Returns:
-            Dictionary representation
+        The result is JSON-safe and round-trips via ``from_dict()``. The
+        associated ``Theme`` (if any) is not serialized here - pass it
+        back in when deserializing.
         """
         return {
             "classes": {name: style.to_dict() for name, style in self._classes.items()},
@@ -360,15 +350,19 @@ def to_dict(self) -> Dict:
 
     @classmethod
     def from_dict(cls, data: Dict, theme: Optional["Theme"] = None) -> "StyleSheet":
-        """
-        Deserialize stylesheet from dictionary.
+        """Reconstruct a ``StyleSheet`` from a ``to_dict()`` result.
 
         Args:
-            data: Dictionary representation
-            theme: Optional theme to include
+            data: Dict produced by ``to_dict()``.
+            theme: Optional theme to attach to the new stylesheet; themes
+                are not serialized by ``to_dict()`` and must be supplied
+                here if they are needed.
 
         Returns:
-            New StyleSheet object
+            A new ``StyleSheet`` with matching classes and breakpoints.
+
+        Raises:
+            ValueError: If a serialized class name fails validation.
         """
         stylesheet = cls(theme=theme)
 
@@ -389,5 +383,5 @@ def from_dict(cls, data: Dict, theme: Optional["Theme"] = None) -> "StyleSheet":
         return stylesheet
 
     def __repr__(self) -> str:
-        """String representation for debugging."""
+        """Return a debug representation listing the registered class count."""
         return f"StyleSheet(classes={self.count_classes()})"
diff --git a/src/nitro_ui/styles/theme.py b/src/nitro_ui/styles/theme.py
index 812bf4c..206d343 100644
--- a/src/nitro_ui/styles/theme.py
+++ b/src/nitro_ui/styles/theme.py
@@ -6,26 +6,20 @@
 
 
 class Theme:
-    """
-    Represents a design theme with colors, typography, spacing, and component styles.
-
-    Usage:
-        # Create custom theme
-        theme = Theme(
-            name="Custom",
-            colors={
-                "primary": "#007bff",
-                "secondary": "#6c757d"
-            }
-        )
-
-        # Use with stylesheet
-        stylesheet = StyleSheet(theme=theme)
-
-        # Or use preset themes
-        theme = Theme.modern()
-        theme = Theme.classic()
-        theme = Theme.minimal()
+    """Named design tokens plus component style presets.
+
+    A ``Theme`` groups colors, typography, spacing, and per-component
+    ``CSSStyle`` objects into a single bundle. When attached to a
+    ``StyleSheet``, the theme's tokens are emitted as CSS custom
+    properties inside a ``:root`` block. Three presets are included:
+    :meth:`modern`, :meth:`classic`, and :meth:`minimal`.
+
+    Example:
+        >>> theme = Theme.modern()
+        >>> "primary" in theme.colors
+        True
+        >>> "--color-primary" in theme.get_css_variables()
+        True
     """
 
     def __init__(
@@ -36,15 +30,19 @@ def __init__(
         spacing: Optional[Dict[str, str]] = None,
         components: Optional[Dict[str, Any]] = None,
     ):
-        """
-        Initialize a Theme.
+        """Create a theme from individual token maps.
 
         Args:
-            name: Theme name
-            colors: Color palette (e.g., {"primary": "#007bff"})
-            typography: Font settings (e.g., {"body": "Arial, sans-serif"})
-            spacing: Spacing scale (e.g., {"sm": "8px", "md": "16px"})
-            components: Pre-styled component definitions
+            name: Human-readable label (e.g. ``"Modern"``).
+            colors: Map of semantic color names to values - emitted as
+                ``--color-<name>`` variables.
+            typography: Font and size map - emitted as ``--font-...``
+                variables. Nested dicts (e.g. ``sizes``) produce
+                ``--font-<group>-<key>`` variables.
+            spacing: Spacing scale - emitted as ``--spacing-<name>``.
+            components: Per-component ``CSSStyle`` presets. Each value
+                may be a single ``CSSStyle`` or a dict of variant names
+                to ``CSSStyle`` (e.g. ``{"button": {"primary": ...}}``).
         """
         self.name = name
         self.colors = colors or {}
@@ -53,11 +51,14 @@ def __init__(
         self.components = components or {}
 
     def get_css_variables(self) -> Dict[str, str]:
-        """
-        Generate CSS variables from theme properties.
+        """Flatten colors, spacing, and typography into CSS custom properties.
+
+        Called by ``StyleSheet.render()`` when a theme is attached, so
+        every variable lands in the ``:root {}`` block.
 
         Returns:
-            Dictionary of CSS variable names and values
+            A dict mapping variable names (``--color-primary``,
+            ``--spacing-md``, ``--font-body``, ...) to their values.
         """
         variables = {}
 
@@ -84,15 +85,20 @@ def get_css_variables(self) -> Dict[str, str]:
     def get_component_style(
         self, component: str, variant: str = "default"
     ) -> Optional[CSSStyle]:
-        """
-        Get a component style from the theme.
+        """Look up a preset ``CSSStyle`` for a component, optionally by variant.
+
+        Components may be stored as a single style or as a map of
+        variant names; this method handles both shapes.
 
         Args:
-            component: Component name (e.g., "button", "card")
-            variant: Variant name (e.g., "primary", "secondary")
+            component: Component key (e.g. ``"button"``, ``"card"``).
+            variant: Variant to pull from a variant map (e.g.
+                ``"primary"``). Ignored when the component is stored as
+                a single style.
 
         Returns:
-            CSSStyle object or None if not found
+            The matching ``CSSStyle``, or ``None`` if the component or
+            variant is not defined on this theme.
         """
         if component not in self.components:
             return None
@@ -107,11 +113,11 @@ def get_component_style(
         return None
 
     def to_dict(self) -> Dict[str, Any]:
-        """
-        Serialize theme to dictionary.
+        """Serialize the theme (including nested component styles) to a dict.
 
-        Returns:
-            Dictionary representation
+        Returns a JSON-safe dict that round-trips via ``from_dict()``.
+        Component entries that are ``CSSStyle`` instances are converted
+        to their dict form.
         """
         return {
             "name": self.name,
@@ -133,14 +139,13 @@ def to_dict(self) -> Dict[str, Any]:
 
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "Theme":
-        """
-        Deserialize theme from dictionary.
+        """Reconstruct a ``Theme`` from a ``to_dict()`` result.
 
         Args:
-            data: Dictionary representation
+            data: Dict previously produced by ``to_dict()``.
 
         Returns:
-            New Theme object
+            A new ``Theme`` with equivalent tokens and components.
         """
         # Reconstruct components
         components = {}
@@ -166,18 +171,17 @@ def from_dict(cls, data: Dict[str, Any]) -> "Theme":
         )
 
     def __repr__(self) -> str:
-        """String representation for debugging."""
+        """Return a debug representation containing the theme name."""
         return f"Theme(name='{self.name}')"
 
     # Preset themes
 
     @classmethod
     def modern(cls) -> "Theme":
-        """
-        Modern theme with clean, contemporary design.
+        """Return the built-in "Modern" preset.
 
-        Returns:
-            Modern Theme object
+        A blue/violet palette with Inter-family fonts and rounded
+        buttons. Suitable for contemporary SaaS interfaces.
         """
         return cls(
             name="Modern",
@@ -256,11 +260,10 @@ def modern(cls) -> "Theme":
 
     @classmethod
     def classic(cls) -> "Theme":
-        """
-        Classic theme with traditional, timeless design.
+        """Return the built-in "Classic" preset.
 
-        Returns:
-            Classic Theme object
+        A Bootstrap-style palette with serif typography and square-ish
+        components. Suitable for editorial or corporate interfaces.
         """
         return cls(
             name="Classic",
@@ -343,11 +346,10 @@ def classic(cls) -> "Theme":
 
     @classmethod
     def minimal(cls) -> "Theme":
-        """
-        Minimal theme with clean, stripped-down design.
+        """Return the built-in "Minimal" preset.
 
-        Returns:
-            Minimal Theme object
+        Black-and-white palette with system fonts, flat buttons, and
+        no rounding. Suitable for content-heavy, text-first interfaces.
         """
         return cls(
             name="Minimal",
diff --git a/src/nitro_ui/tags/form.py b/src/nitro_ui/tags/form.py
index 4a072ed..ca610be 100644
--- a/src/nitro_ui/tags/form.py
+++ b/src/nitro_ui/tags/form.py
@@ -16,8 +16,27 @@
 
 
 class Select(BaseSelect):
+    """HTML ``<select>`` dropdown with a convenience option builder."""
+
     @classmethod
-    def with_items(cls, *items, **kwargs):
+    def with_items(cls, *items, **kwargs) -> "Select":
+        """Build a ``<select>`` and wrap plain items as ``<option>`` children.
+
+        ``HTMLElement`` arguments (including ``Option`` / ``Optgroup``)
+        are appended unchanged. Any other value is wrapped in an
+        ``Option(item)``.
+
+        Args:
+            *items: Option elements or plain values.
+            **kwargs: Attributes forwarded to the ``<select>``.
+
+        Returns:
+            A populated ``Select`` instance.
+
+        Example:
+            >>> Select.with_items("Red", "Green", "Blue", name="color").render()
+            '<select name="color"><option>Red</option><option>Green</option><option>Blue</option></select>'
+        """
         opt = cls(**kwargs)
         for item in items:
             if isinstance(item, HTMLElement):
@@ -31,6 +50,11 @@ def with_items(cls, *items, **kwargs):
 
 
 def label_extra_init(self, kwargs):
+    """Translate ``for_element`` to ``for`` when a ``Label`` is constructed.
+
+    NitroUI normalizes Python-keyword-clashing attrs as ``for_element``;
+    the ``<label>`` tag uses the HTML name directly.
+    """
     if "for_element" in kwargs:
         kwargs["for"] = kwargs.pop("for_element")
 
@@ -39,11 +63,29 @@ def label_extra_init(self, kwargs):
 
 
 class Form(HTMLElement):
+    """HTML ``<form>`` element with a convenience field-appending builder."""
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **{**kwargs, "tag": "form"})
 
     @classmethod
-    def with_fields(cls, *items, **kwargs):
+    def with_fields(cls, *items, **kwargs) -> "Form":
+        """Build a ``<form>`` from a flat list of fields and text nodes.
+
+        Equivalent to ``Form(*items, **kwargs)`` but with a type guard -
+        anything that is not an ``HTMLElement`` or string raises
+        ``TypeError`` rather than silently misbehaving.
+
+        Args:
+            *items: Elements or strings to place inside the form.
+            **kwargs: Attributes forwarded to the ``<form>``.
+
+        Returns:
+            A populated ``Form`` instance.
+
+        Raises:
+            TypeError: If any item is not an ``HTMLElement`` or string.
+        """
         form = cls(**kwargs)
         for item in items:
             if isinstance(item, HTMLElement):
diff --git a/src/nitro_ui/tags/html.py b/src/nitro_ui/tags/html.py
index 01ecc22..4f8133c 100644
--- a/src/nitro_ui/tags/html.py
+++ b/src/nitro_ui/tags/html.py
@@ -3,6 +3,17 @@
 
 
 class HTML(HTMLElement):
+    """Root ``<html>`` element that also emits ``<!DOCTYPE html>``.
+
+    Defaults ``lang="en"`` and ``dir="ltr"`` if not overridden. When
+    rendered it prepends the HTML5 doctype declaration, so it is
+    intended as the outermost node of a full page.
+
+    Example:
+        >>> HTML(Head(Title("Home")), Body(H1("Hi"))).render().startswith("<!DOCTYPE html>")
+        True
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(
             *args,
diff --git a/src/nitro_ui/tags/lists.py b/src/nitro_ui/tags/lists.py
index 77bfb42..92024a1 100644
--- a/src/nitro_ui/tags/lists.py
+++ b/src/nitro_ui/tags/lists.py
@@ -8,11 +8,29 @@
 
 
 class UnorderedList(HTMLElement):
+    """HTML ``<ul>`` element with a convenience item-wrapping builder."""
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **{**kwargs, "tag": "ul"})
 
     @classmethod
-    def with_items(cls, *items, **kwargs):
+    def with_items(cls, *items, **kwargs) -> "UnorderedList":
+        """Build a ``<ul>`` and wrap plain items as ``<li>`` children.
+
+        ``HTMLElement`` arguments are appended unchanged; anything else
+        (strings, numbers, ...) is wrapped in a ``ListItem``.
+
+        Args:
+            *items: Child elements or plain values.
+            **kwargs: Attributes forwarded to the ``<ul>``.
+
+        Returns:
+            A populated ``UnorderedList`` instance.
+
+        Example:
+            >>> UnorderedList.with_items("Apples", "Oranges").render()
+            '<ul><li>Apples</li><li>Oranges</li></ul>'
+        """
         ul = cls(**kwargs)
         for item in items:
             if isinstance(item, HTMLElement):
@@ -26,11 +44,25 @@ def with_items(cls, *items, **kwargs):
 
 
 class OrderedList(HTMLElement):
+    """HTML ``<ol>`` element with a convenience item-wrapping builder."""
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **{**kwargs, "tag": "ol"})
 
     @classmethod
-    def with_items(cls, *items, **kwargs):
+    def with_items(cls, *items, **kwargs) -> "OrderedList":
+        """Build an ``<ol>`` and wrap plain items as ``<li>`` children.
+
+        ``HTMLElement`` arguments are appended unchanged; anything else
+        is wrapped in a ``ListItem``.
+
+        Args:
+            *items: Child elements or plain values.
+            **kwargs: Attributes forwarded to the ``<ol>``.
+
+        Returns:
+            A populated ``OrderedList`` instance.
+        """
         ol = cls(**kwargs)
         for item in items:
             if isinstance(item, HTMLElement):
diff --git a/src/nitro_ui/tags/table.py b/src/nitro_ui/tags/table.py
index 745db81..8bcaf1b 100644
--- a/src/nitro_ui/tags/table.py
+++ b/src/nitro_ui/tags/table.py
@@ -16,11 +16,33 @@
 
 
 class Table(HTMLElement):
+    """HTML ``<table>`` element with helpers for loading data from files."""
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **{**kwargs, "tag": "table"})
 
     @classmethod
     def from_csv(cls, file_path: str, encoding: str = "utf-8") -> "Table":
+        """Load a CSV file into a ``<table>`` of ``<tr>`` / ``<td>`` rows.
+
+        Every row becomes a ``TableRow``; every cell becomes a
+        ``TableDataCell``. The first row is not treated specially - wrap
+        it in a ``TableHeader`` yourself if you need ``<th>``.
+
+        Args:
+            file_path: Path to a CSV file on disk.
+            encoding: Text encoding to read the file as.
+
+        Returns:
+            A populated ``Table`` instance.
+
+        Raises:
+            ValueError: If the file is missing, has an encoding mismatch,
+                or cannot be parsed as CSV.
+
+        Example:
+            >>> Table.from_csv("data.csv").render()  # doctest: +SKIP
+        """
         table = cls()
         try:
             with open(file_path, mode="r", encoding=encoding) as file:
@@ -40,6 +62,22 @@ def from_csv(cls, file_path: str, encoding: str = "utf-8") -> "Table":
 
     @classmethod  # type: ignore[override]
     def from_json(cls, file_path: str, encoding: str = "utf-8") -> "Table":
+        """Load a JSON file (a list of row-lists) into a ``<table>``.
+
+        The file must decode to a list of lists; each inner list is
+        rendered as a row of ``<td>`` cells (values are stringified).
+
+        Args:
+            file_path: Path to a JSON file on disk.
+            encoding: Text encoding to read the file as.
+
+        Returns:
+            A populated ``Table`` instance.
+
+        Raises:
+            ValueError: If the file is missing, has an encoding mismatch,
+                is not valid JSON, or is not a list-of-lists.
+        """
         table = cls()
         try:
             with open(file_path, mode="r", encoding=encoding) as file:
diff --git a/src/nitro_ui/tags/tag_factory.py b/src/nitro_ui/tags/tag_factory.py
index 0878530..d1488b0 100644
--- a/src/nitro_ui/tags/tag_factory.py
+++ b/src/nitro_ui/tags/tag_factory.py
@@ -1,8 +1,49 @@
+from typing import Callable, Optional, Type
+
 from nitro_ui.core.element import HTMLElement, register_tag
 
 
-# Factory function to create simple tag classes
-def simple_tag_class(tag, self_closing=False, extra_init=None):
+def simple_tag_class(
+    tag: str,
+    self_closing: bool = False,
+    extra_init: Optional[Callable[[HTMLElement, dict], None]] = None,
+) -> Type[HTMLElement]:
+    """Build a lightweight ``HTMLElement`` subclass bound to a tag name.
+
+    Most public tag classes in NitroUI (``Div``, ``H1``, ``Input``,
+    ``Meta``, ...) are produced by this factory. Each generated class
+    accepts the same arguments as ``HTMLElement`` - positional children
+    and keyword attributes - but hard-codes the ``tag`` and
+    ``self_closing`` values so callers never specify them.
+
+    The produced class is also registered in the tag registry so that
+    ``HTMLElement.from_dict()`` and ``from_html()`` can round-trip
+    instances back into the same subclass.
+
+    Args:
+        tag: HTML tag name to bind (e.g. ``"div"``, ``"img"``).
+        self_closing: If ``True``, the generated class renders as
+            ``<tag />`` with no closing tag. Use for void elements like
+            ``img``, ``br``, ``input``, ``meta``.
+        extra_init: Optional callback invoked at construction time with
+            ``(instance, kwargs)``. The callback may mutate the kwargs
+            dict in place to rewrite or inject attributes before
+            ``HTMLElement.__init__`` runs - used, for example, by
+            ``Label`` to convert a ``for_element`` kwarg to ``for``.
+
+    Returns:
+        A new ``HTMLElement`` subclass named after ``tag`` (e.g.
+        ``"div"`` -> class named ``Div``).
+
+    Raises:
+        TypeError: If ``tag`` is not a string, or ``extra_init`` is not
+            callable.
+
+    Example:
+        >>> MyTag = simple_tag_class("my-tag")
+        >>> MyTag("Hello", id="t1").render()
+        '<my-tag id="t1">Hello</my-tag>'
+    """
     if not isinstance(tag, str):
         raise TypeError(f"tag must be a string, got {type(tag)}")
 
@@ -10,6 +51,13 @@ def simple_tag_class(tag, self_closing=False, extra_init=None):
         raise TypeError("extra_init must be callable")
 
     class _Tag(HTMLElement):
+        """HTML element class for a single fixed tag.
+
+        Accepts positional children (elements or strings) and keyword
+        attributes; ``tag`` and ``self_closing`` are bound at class
+        creation time. See :func:`simple_tag_class` for details.
+        """
+
         def __init__(self, *args, **kwargs):
             if extra_init:
                 extra_init(self, kwargs)
@@ -22,12 +70,12 @@ def __init__(self, *args, **kwargs):
                 },
             )
 
-    # @NOTE __qualname__ for serialization
+    # __qualname__ is set so pickling and serialization refer to the
+    # logical class name (e.g. "Div") rather than "_Tag".
     class_name = tag.capitalize() if tag.islower() else tag
     _Tag.__name__ = class_name
     _Tag.__qualname__ = class_name
 
-    # Register tag for from_dict() subclass reconstruction
     register_tag(tag, _Tag)
 
     return _Tag