From 6f882c0658ed31d6580043fd64756150c8a9d09c Mon Sep 17 00:00:00 2001
From: Sean N <sean@isean.co.za>
Date: Mon, 10 Nov 2025 21:45:51 +0200
Subject: [PATCH 1/2] Cleanups

---
 src/ydnatl/core/element.py     |  18 +++---
 src/ydnatl/core/fragment.py    |  13 +++--
 src/ydnatl/tags/tag_factory.py |   1 +
 tests/test_element.py          | 102 +++++++++++++++++----------------
 tests/test_fragment.py         |  90 +++++++----------------------
 5 files changed, 93 insertions(+), 131 deletions(-)

diff --git a/src/ydnatl/core/element.py b/src/ydnatl/core/element.py
index fdf97f1..d17a402 100644
--- a/src/ydnatl/core/element.py
+++ b/src/ydnatl/core/element.py
@@ -5,18 +5,18 @@
 import uuid
 from typing import Callable, Any, Iterator, Union, List, TypeVar
 
-T = TypeVar('T', bound='HTMLElement')
+T = TypeVar("T", bound="HTMLElement")
 
 
 class HTMLElement:
     __slots__ = ["_tag", "_children", "_text", "_attributes", "_self_closing"]
 
     def __init__(
-            self,
-            *children: Union["HTMLElement", str, List[Any]],
-            tag: str,
-            self_closing: bool = False,
-            **attributes: str,
+        self,
+        *children: Union["HTMLElement", str, List[Any]],
+        tag: str,
+        self_closing: bool = False,
+        **attributes: str,
     ):
         PRESERVE_UNDERSCORE = {"class_name"}
 
@@ -100,7 +100,7 @@ def append(self, *children: Union["HTMLElement", str, List[Any]]) -> "HTMLElemen
         return self
 
     def filter(
-            self, condition: Callable[[Any], bool], recursive: bool = False
+        self, condition: Callable[[Any], bool], recursive: bool = False
     ) -> Iterator["HTMLElement"]:
         """Yields children (and optionally descendants) that meet the condition."""
         for child in self._children:
@@ -288,7 +288,7 @@ def replace_child(self, old_index: int, new_child: "HTMLElement") -> None:
         self._children[old_index] = new_child
 
     def find_by_attribute(
-            self, attr_name: str, attr_value: Any
+        self, attr_name: str, attr_value: Any
     ) -> Union["HTMLElement", None]:
         """Finds a child by an attribute."""
 
@@ -470,7 +470,7 @@ def from_dict(cls, data: dict) -> "HTMLElement":
         element = cls(
             tag=data["tag"],
             self_closing=data.get("self_closing", False),
-            **data.get("attributes", {})
+            **data.get("attributes", {}),
         )
 
         if "text" in data and data["text"]:
diff --git a/src/ydnatl/core/fragment.py b/src/ydnatl/core/fragment.py
index d779a15..3d21c2f 100644
--- a/src/ydnatl/core/fragment.py
+++ b/src/ydnatl/core/fragment.py
@@ -16,7 +16,9 @@ class Fragment(HTMLElement):
         # Instead of: <fragment><h1>Title</h1><p>Content</p></fragment>
     """
 
-    def __init__(self, *children: Union["HTMLElement", str, List[Any]], **attributes: str):
+    def __init__(
+        self, *children: Union["HTMLElement", str, List[Any]], **attributes: str
+    ):
         # Initialize with a dummy tag name since we won't render it
         super().__init__(*children, tag="fragment", **attributes)
 
@@ -35,19 +37,18 @@ def render(self, pretty: bool = False, _indent: int = 0) -> str:
         # Render only children, not the fragment tag itself
         if pretty:
             result = "".join(
-                child.render(pretty=True, _indent=_indent)
-                for child in self._children
+                child.render(pretty=True, _indent=_indent) for child in self._children
             )
         else:
             result = "".join(
-                child.render(pretty=False, _indent=_indent)
-                for child in self._children
+                child.render(pretty=False, _indent=_indent) for child in self._children
             )
 
         # Include text content if any
         if self._text:
             import html
+
             result = html.escape(self._text) + result
 
         self.on_after_render()
-        return result
\ No newline at end of file
+        return result
diff --git a/src/ydnatl/tags/tag_factory.py b/src/ydnatl/tags/tag_factory.py
index 7db3142..21855fc 100644
--- a/src/ydnatl/tags/tag_factory.py
+++ b/src/ydnatl/tags/tag_factory.py
@@ -21,6 +21,7 @@ def __init__(self, *args, **kwargs):
                     **({"self_closing": True} if self_closing else {}),
                 },
             )
+
     # @NOTE __qualname__ for serialization
     class_name = tag.capitalize() if tag.islower() else tag
     _Tag.__name__ = class_name
diff --git a/tests/test_element.py b/tests/test_element.py
index 382cd43..f458381 100644
--- a/tests/test_element.py
+++ b/tests/test_element.py
@@ -246,6 +246,7 @@ def test_html_escaping_normal_content(self):
     def test_to_json_simple_element(self):
         """Test serialization of a simple element to JSON."""
         import json
+
         element = HTMLElement("Hello", tag="div", id="test", class_name="container")
         json_str = element.to_json()
         self.assertIsInstance(json_str, str)
@@ -270,6 +271,7 @@ def test_to_json_nested_elements(self):
 
         json_str = parent.to_json()
         import json
+
         data = json.loads(json_str)
 
         self.assertEqual(len(data["children"]), 2)
@@ -283,7 +285,7 @@ def test_from_dict_simple_element(self):
             "self_closing": False,
             "attributes": {"id": "test", "class": "container"},
             "text": "Hello",
-            "children": []
+            "children": [],
         }
         element = HTMLElement.from_dict(data)
 
@@ -300,7 +302,7 @@ def test_from_dict_self_closing_element(self):
             "self_closing": True,
             "attributes": {},
             "text": "",
-            "children": []
+            "children": [],
         }
         element = HTMLElement.from_dict(data)
 
@@ -321,16 +323,16 @@ def test_from_dict_nested_elements(self):
                     "self_closing": False,
                     "attributes": {},
                     "text": "Child 1",
-                    "children": []
+                    "children": [],
                 },
                 {
                     "tag": "span",
                     "self_closing": False,
                     "attributes": {},
                     "text": "Child 2",
-                    "children": []
-                }
-            ]
+                    "children": [],
+                },
+            ],
         }
         element = HTMLElement.from_dict(data)
 
@@ -374,12 +376,9 @@ def test_round_trip_serialization(self):
         section = HTMLElement(tag="section")
         section.append(
             HTMLElement("Paragraph 1", tag="p"),
-            HTMLElement("Paragraph 2", tag="p", class_name="highlight")
-        )
-        original.append(
-            HTMLElement("Header", tag="h1"),
-            section
+            HTMLElement("Paragraph 2", tag="p", class_name="highlight"),
         )
+        original.append(HTMLElement("Header", tag="h1"), section)
 
         json_str = original.to_json()
 
@@ -400,7 +399,7 @@ def test_round_trip_with_attributes(self):
             type="text",
             name="username",
             placeholder="Enter username",
-            data_validation="required"
+            data_validation="required",
         )
 
         json_str = original.to_json()
@@ -408,8 +407,13 @@ def test_round_trip_with_attributes(self):
 
         self.assertEqual(original.get_attribute("type"), restored.get_attribute("type"))
         self.assertEqual(original.get_attribute("name"), restored.get_attribute("name"))
-        self.assertEqual(original.get_attribute("placeholder"), restored.get_attribute("placeholder"))
-        self.assertEqual(original.get_attribute("data-validation"), restored.get_attribute("data-validation"))
+        self.assertEqual(
+            original.get_attribute("placeholder"), restored.get_attribute("placeholder")
+        )
+        self.assertEqual(
+            original.get_attribute("data-validation"),
+            restored.get_attribute("data-validation"),
+        )
         self.assertEqual(str(original), str(restored))
 
     def test_serialization_deeply_nested(self):
@@ -426,22 +430,22 @@ def test_serialization_deeply_nested(self):
         json_str = root.to_json()
         restored = HTMLElement.from_json(json_str)
 
-        self.assertEqual(restored.children[0].children[0].children[0].text, "Deep content")
+        self.assertEqual(
+            restored.children[0].children[0].children[0].text, "Deep content"
+        )
         self.assertEqual(str(root), str(restored))
 
-
     def test_render_pretty_simple(self):
         """Test pretty printing with simple nested structure."""
         element = HTMLElement(tag="div", id="container")
-        element.append(
-            HTMLElement("Hello", tag="h1"),
-            HTMLElement("World", tag="p")
-        )
+        element.append(HTMLElement("Hello", tag="h1"), HTMLElement("World", tag="p"))
 
         # Test compact (default)
         compact = element.render(pretty=False)
         self.assertNotIn("\n", compact)
-        self.assertEqual(compact, '<div id="container"><h1>Hello</h1><p>World</p></div>')
+        self.assertEqual(
+            compact, '<div id="container"><h1>Hello</h1><p>World</p></div>'
+        )
 
         # Test pretty
         pretty = element.render(pretty=True)
@@ -482,11 +486,7 @@ def test_add_style_single(self):
     def test_add_styles_multiple(self):
         """Test adding multiple CSS styles at once."""
         element = HTMLElement(tag="div")
-        element.add_styles({
-            "color": "blue",
-            "font-size": "14px",
-            "margin": "10px"
-        })
+        element.add_styles({"color": "blue", "font-size": "14px", "margin": "10px"})
 
         style = element.get_attribute("style")
         self.assertIn("color: blue", style)
@@ -514,11 +514,7 @@ def test_get_style(self):
     def test_remove_style(self):
         """Test removing CSS styles."""
         element = HTMLElement(tag="div")
-        element.add_styles({
-            "color": "red",
-            "font-size": "14px",
-            "margin": "10px"
-        })
+        element.add_styles({"color": "red", "font-size": "14px", "margin": "10px"})
 
         element.remove_style("margin")
 
@@ -540,7 +536,9 @@ def test_remove_style_last_one(self):
 
     def test_parse_styles(self):
         """Test the _parse_styles static method."""
-        styles_dict = HTMLElement._parse_styles("color: red; font-size: 14px; margin: 10px")
+        styles_dict = HTMLElement._parse_styles(
+            "color: red; font-size: 14px; margin: 10px"
+        )
 
         self.assertEqual(styles_dict["color"], "red")
         self.assertEqual(styles_dict["font-size"], "14px")
@@ -586,9 +584,11 @@ def test_method_chaining_append(self):
         self.assertIs(result, element)
 
         # Test actual chaining
-        element = (HTMLElement(tag="div")
-                   .append(HTMLElement(tag="h1"))
-                   .append(HTMLElement(tag="p")))
+        element = (
+            HTMLElement(tag="div")
+            .append(HTMLElement(tag="h1"))
+            .append(HTMLElement(tag="p"))
+        )
 
         self.assertEqual(element.count_children(), 2)
 
@@ -607,9 +607,11 @@ def test_method_chaining_add_attribute(self):
         self.assertIs(result, element)
 
         # Test actual chaining
-        element = (HTMLElement(tag="div")
-                   .add_attribute("id", "main")
-                   .add_attribute("class", "container"))
+        element = (
+            HTMLElement(tag="div")
+            .add_attribute("id", "main")
+            .add_attribute("class", "container")
+        )
 
         self.assertEqual(element.get_attribute("id"), "main")
         self.assertEqual(element.get_attribute("class"), "container")
@@ -636,9 +638,11 @@ def test_method_chaining_add_style(self):
         self.assertIs(result, element)
 
         # Test actual chaining
-        element = (HTMLElement(tag="div")
-                   .add_style("color", "blue")
-                   .add_style("font-size", "14px"))
+        element = (
+            HTMLElement(tag="div")
+            .add_style("color", "blue")
+            .add_style("font-size", "14px")
+        )
 
         self.assertEqual(element.get_style("color"), "blue")
         self.assertEqual(element.get_style("font-size"), "14px")
@@ -676,13 +680,15 @@ def test_method_chaining_remove_all(self):
 
     def test_method_chaining_complex(self):
         """Test complex method chaining scenario."""
-        element = (HTMLElement(tag="div")
-                   .add_attribute("id", "container")
-                   .add_attribute("class", "wrapper")
-                   .add_style("background", "#f0f0f0")
-                   .add_styles({"padding": "20px", "margin": "10px"})
-                   .append(HTMLElement("Title", tag="h1"))
-                   .append(HTMLElement("Content", tag="p")))
+        element = (
+            HTMLElement(tag="div")
+            .add_attribute("id", "container")
+            .add_attribute("class", "wrapper")
+            .add_style("background", "#f0f0f0")
+            .add_styles({"padding": "20px", "margin": "10px"})
+            .append(HTMLElement("Title", tag="h1"))
+            .append(HTMLElement("Content", tag="p"))
+        )
 
         self.assertEqual(element.get_attribute("id"), "container")
         self.assertEqual(element.get_attribute("class"), "wrapper")
diff --git a/tests/test_fragment.py b/tests/test_fragment.py
index 35f1461..821032e 100644
--- a/tests/test_fragment.py
+++ b/tests/test_fragment.py
@@ -10,10 +10,7 @@ class TestFragment(unittest.TestCase):
 
     def test_fragment_basic(self):
         """Test basic Fragment rendering without wrapper tag."""
-        fragment = Fragment(
-            H1("Title"),
-            Paragraph("Content")
-        )
+        fragment = Fragment(H1("Title"), Paragraph("Content"))
 
         rendered = str(fragment)
         self.assertEqual(rendered, "<h1>Title</h1><p>Content</p>")
@@ -28,9 +25,7 @@ def test_fragment_empty(self):
 
     def test_fragment_single_child(self):
         """Test Fragment with single child."""
-        fragment = Fragment(
-            Paragraph("Single child")
-        )
+        fragment = Fragment(Paragraph("Single child"))
 
         rendered = str(fragment)
         self.assertEqual(rendered, "<p>Single child</p>")
@@ -41,7 +36,7 @@ def test_fragment_multiple_children(self):
             H1("Header"),
             Paragraph("Paragraph 1"),
             Paragraph("Paragraph 2"),
-            Span("Inline text")
+            Span("Inline text"),
         )
 
         rendered = str(fragment)
@@ -51,13 +46,7 @@ def test_fragment_multiple_children(self):
     def test_fragment_nested_elements(self):
         """Test Fragment with nested HTML elements."""
         fragment = Fragment(
-            Div(
-                H1("Title"),
-                Paragraph("Content")
-            ),
-            Section(
-                Paragraph("More content")
-            )
+            Div(H1("Title"), Paragraph("Content")), Section(Paragraph("More content"))
         )
 
         rendered = str(fragment)
@@ -75,11 +64,7 @@ def test_fragment_with_text(self):
 
     def test_fragment_mixed_text_and_elements(self):
         """Test Fragment with both text and elements."""
-        fragment = Fragment(
-            "Text before",
-            Paragraph("Middle"),
-            "Text after"
-        )
+        fragment = Fragment("Text before", Paragraph("Middle"), "Text after")
 
         # Note: text is handled differently, need to test actual output
         rendered = str(fragment)
@@ -88,11 +73,7 @@ def test_fragment_mixed_text_and_elements(self):
     def test_fragment_pretty_printing(self):
         """Test Fragment with pretty printing enabled."""
         fragment = Fragment(
-            Div(
-                H1("Title"),
-                Paragraph("Content")
-            ),
-            Paragraph("Outside")
+            Div(H1("Title"), Paragraph("Content")), Paragraph("Outside")
         )
 
         pretty = fragment.render(pretty=True)
@@ -111,9 +92,7 @@ def test_fragment_append_children(self):
 
     def test_fragment_prepend_children(self):
         """Test prepending children to Fragment."""
-        fragment = Fragment(
-            Paragraph("Second")
-        )
+        fragment = Fragment(Paragraph("Second"))
         fragment.prepend(H1("First"))
 
         rendered = str(fragment)
@@ -121,10 +100,7 @@ def test_fragment_prepend_children(self):
 
     def test_fragment_clear(self):
         """Test clearing Fragment children."""
-        fragment = Fragment(
-            H1("Title"),
-            Paragraph("Content")
-        )
+        fragment = Fragment(H1("Title"), Paragraph("Content"))
 
         fragment.clear()
         rendered = str(fragment)
@@ -132,20 +108,13 @@ def test_fragment_clear(self):
 
     def test_fragment_count_children(self):
         """Test counting Fragment children."""
-        fragment = Fragment(
-            H1("Title"),
-            Paragraph("Content 1"),
-            Paragraph("Content 2")
-        )
+        fragment = Fragment(H1("Title"), Paragraph("Content 1"), Paragraph("Content 2"))
 
         self.assertEqual(fragment.count_children(), 3)
 
     def test_fragment_nested_in_div(self):
         """Test using Fragment inside another element."""
-        fragment = Fragment(
-            H1("Title"),
-            Paragraph("Content")
-        )
+        fragment = Fragment(H1("Title"), Paragraph("Content"))
 
         div = Div()
         div.append(fragment)
@@ -187,11 +156,7 @@ def test_fragment_list_composition(self):
 
     def test_fragment_with_attributes(self):
         """Test that Fragment ignores attributes (doesn't render them)."""
-        fragment = Fragment(
-            H1("Title"),
-            id="ignored",
-            class_name="also-ignored"
-        )
+        fragment = Fragment(H1("Title"), id="ignored", class_name="also-ignored")
 
         rendered = str(fragment)
         self.assertNotIn("id", rendered)
@@ -200,10 +165,12 @@ def test_fragment_with_attributes(self):
 
     def test_fragment_method_chaining(self):
         """Test method chaining with Fragment."""
-        fragment = (Fragment()
-                    .append(H1("Title"))
-                    .append(Paragraph("Content 1"))
-                    .append(Paragraph("Content 2")))
+        fragment = (
+            Fragment()
+            .append(H1("Title"))
+            .append(Paragraph("Content 1"))
+            .append(Paragraph("Content 2"))
+        )
 
         self.assertEqual(fragment.count_children(), 3)
         rendered = str(fragment)
@@ -226,10 +193,7 @@ def test_fragment_context_manager(self):
 
     def test_fragment_clone(self):
         """Test cloning a Fragment."""
-        original = Fragment(
-            H1("Title"),
-            Paragraph("Content")
-        )
+        original = Fragment(H1("Title"), Paragraph("Content"))
 
         cloned = original.clone()
 
@@ -240,10 +204,7 @@ def test_fragment_clone(self):
     def test_fragment_filter(self):
         """Test filtering Fragment children."""
         fragment = Fragment(
-            H1("Title"),
-            Paragraph("Para 1"),
-            Span("Span"),
-            Paragraph("Para 2")
+            H1("Title"), Paragraph("Para 1"), Span("Span"), Paragraph("Para 2")
         )
 
         paragraphs = list(fragment.filter(lambda x: x.tag == "p"))
@@ -252,9 +213,7 @@ def test_fragment_filter(self):
     def test_fragment_find_by_attribute(self):
         """Test finding elements by attribute in Fragment."""
         fragment = Fragment(
-            H1("Title", id="header"),
-            Paragraph("Content", id="main"),
-            Span("Text")
+            H1("Title", id="header"), Paragraph("Content", id="main"), Span("Text")
         )
 
         found = fragment.find_by_attribute("id", "main")
@@ -263,12 +222,7 @@ def test_fragment_find_by_attribute(self):
 
     def test_fragment_compact_vs_pretty(self):
         """Test compact vs pretty rendering of Fragment."""
-        fragment = Fragment(
-            Div(
-                H1("Title"),
-                Paragraph("Content")
-            )
-        )
+        fragment = Fragment(Div(H1("Title"), Paragraph("Content")))
 
         # Compact
         compact = fragment.render(pretty=False)
@@ -281,4 +235,4 @@ def test_fragment_compact_vs_pretty(self):
 
 
 if __name__ == "__main__":
-    unittest.main()
\ No newline at end of file
+    unittest.main()

From 31bc7305240cd7d838c5f5f4fedbe4e35a6c2de7 Mon Sep 17 00:00:00 2001
From: Sean N <sean@isean.co.za>
Date: Tue, 11 Nov 2025 11:06:47 +0200
Subject: [PATCH 2/2] Added: Styling engine, LLM_GUIDE and additional
 documentation

---
 LLM_GUIDE.md                    | 2138 +++++++++++++++++++++++++++++++
 README.md                       |  226 +++-
 examples/stylesheet_example.py  |  295 +++++
 pyproject.toml                  |    2 +-
 src/ydnatl/__init__.py          |   11 +
 src/ydnatl/core/fragment.py     |    1 +
 src/ydnatl/core/parser.py       |  134 ++
 src/ydnatl/styles/__init__.py   |   11 +
 src/ydnatl/styles/style.py      |  201 +++
 src/ydnatl/styles/stylesheet.py |  316 +++++
 src/ydnatl/styles/theme.py      |  428 +++++++
 tests/test_fragment.py          |    4 +-
 tests/test_parser.py            |  357 ++++++
 tests/test_styles.py            |  408 ++++++
 tests/test_text.py              |    2 +-
 15 files changed, 4529 insertions(+), 5 deletions(-)
 create mode 100644 LLM_GUIDE.md
 create mode 100644 examples/stylesheet_example.py
 create mode 100644 src/ydnatl/core/parser.py
 create mode 100644 src/ydnatl/styles/__init__.py
 create mode 100644 src/ydnatl/styles/style.py
 create mode 100644 src/ydnatl/styles/stylesheet.py
 create mode 100644 src/ydnatl/styles/theme.py
 create mode 100644 tests/test_parser.py
 create mode 100644 tests/test_styles.py

diff --git a/LLM_GUIDE.md b/LLM_GUIDE.md
new file mode 100644
index 0000000..5376cad
--- /dev/null
+++ b/LLM_GUIDE.md
@@ -0,0 +1,2138 @@
+# YDNATL - LLM Developer Guide
+
+**Version:** 1.0.x
+**Language:** Python 3.8+
+**Dependencies:** None (pure Python, uses only stdlib)
+
+## Overview
+
+YDNATL (You Don't Need Another Template Language) is a Python library for programmatic HTML generation. It uses a declarative, class-based API similar to Flutter's widget system. All elements are subclasses of `HTMLElement` and support method chaining, context managers, and serialization.
+
+## Core Concepts
+
+### 1. Element Hierarchy
+- All HTML elements inherit from `HTMLElement`
+- Elements can have children (other elements)
+- Elements have attributes (HTML attributes like id, class, etc.)
+- Elements have text content
+- Some elements are self-closing (br, img, hr, input, etc.)
+
+### 2. Rendering
+- `render()` method converts element tree to HTML string
+- Supports compact (default) and pretty (indented) output
+- Automatic HTML entity escaping for security
+
+### 3. Serialization
+- Elements can be serialized to JSON (`to_json()`)
+- Elements can be deserialized from JSON (`from_json()`)
+- Elements can be parsed from HTML strings (`from_html()`)
+
+---
+
+## Import Patterns
+
+### Import Everything (Quick Start)
+```python
+from ydnatl import *
+```
+
+### Selective Imports (Recommended for Production)
+```python
+from ydnatl import HTMLElement, Fragment, from_html
+from ydnatl.tags.text import H1, Paragraph, Span
+from ydnatl.tags.layout import Div, Section
+from ydnatl.tags.form import Form, Input, Button
+```
+
+### Import from Core
+```python
+from ydnatl.core.element import HTMLElement
+from ydnatl.core.fragment import Fragment
+from ydnatl.core.parser import from_html
+```
+
+---
+
+## HTMLElement Class
+
+**Location:** `ydnatl.core.element.HTMLElement`
+
+### Constructor
+
+```python
+HTMLElement(
+    *children,           # Variable number of child elements or text
+    tag: str = "div",   # HTML tag name
+    text: str = "",     # Text content
+    self_closing: bool = False,  # Whether element is self-closing
+    **attributes        # HTML attributes as keyword arguments
+)
+```
+
+**Special Attribute Handling:**
+- `class_name` → renders as `class` attribute
+- `data_*` attributes → preserved with hyphens (data-value)
+- Boolean attributes (checked, disabled) → rendered without values when True
+- `style` → can be string or managed via style helper methods
+
+**Example:**
+```python
+div = HTMLElement(
+    H1("Title"),
+    Paragraph("Content"),
+    tag="div",
+    id="main",
+    class_name="container",
+    data_value="123"
+)
+```
+
+### Properties
+
+| Property       | Type                     | Description       | Mutable               |
+|----------------|--------------------------|-------------------|-----------------------|
+| `tag`          | str                      | HTML tag name     | Yes                   |
+| `children`     | List[HTMLElement \| str] | Child elements    | Yes (but use methods) |
+| `text`         | str                      | Text content      | Yes                   |
+| `attributes`   | Dict[str, str]           | HTML attributes   | Yes (but use methods) |
+| `self_closing` | bool                     | Self-closing flag | Yes                   |
+
+---
+
+## Element Manipulation Methods
+
+### Adding Children
+
+#### append(*children) → self
+Adds children to end of children list.
+
+```python
+div = Div()
+div.append(H1("Title"))
+div.append(Paragraph("Para 1"), Paragraph("Para 2"))
+```
+
+**Parameters:**
+- `*children`: Variable number of HTMLElement or str
+
+**Returns:** self (for chaining)
+
+#### prepend(*children) → self
+Adds children to beginning of children list.
+
+```python
+div = Div(Paragraph("Second"))
+div.prepend(H1("First"))  # H1 now comes before Paragraph
+```
+
+**Parameters:**
+- `*children`: Variable number of HTMLElement or str
+
+**Returns:** self (for chaining)
+
+### Removing Children
+
+#### clear() → self
+Removes all children.
+
+```python
+div.clear()  # Now has no children
+```
+
+**Returns:** self (for chaining)
+
+#### pop(index: int = -1) → HTMLElement
+Removes and returns child at index.
+
+```python
+last_child = div.pop()      # Remove last child
+first_child = div.pop(0)    # Remove first child
+```
+
+**Parameters:**
+- `index`: int (default: -1) - Index of child to remove
+
+**Returns:** Removed HTMLElement
+
+#### remove_all(condition: Callable) → self
+Removes all children matching condition.
+
+```python
+# Remove all paragraphs
+div.remove_all(lambda el: el.tag == "p")
+
+# Remove elements with specific class
+div.remove_all(lambda el: el.get_attribute("class_name") == "hidden")
+```
+
+**Parameters:**
+- `condition`: Callable[[HTMLElement], bool] - Function that returns True for elements to remove
+
+**Returns:** self (for chaining)
+
+### Querying Children
+
+#### filter(condition: Callable) → Iterator[HTMLElement]
+Returns iterator of children matching condition.
+
+```python
+# Get all paragraphs
+paragraphs = list(div.filter(lambda el: el.tag == "p"))
+
+# Get elements with specific attribute
+highlighted = list(div.filter(lambda el: el.has_attribute("highlight")))
+```
+
+**Parameters:**
+- `condition`: Callable[[HTMLElement], bool]
+
+**Returns:** Iterator[HTMLElement]
+
+#### find_by_attribute(key: str, value: str) → Optional[HTMLElement]
+Finds first child with matching attribute.
+
+```python
+main = div.find_by_attribute("id", "main")
+container = div.find_by_attribute("class_name", "container")
+```
+
+**Parameters:**
+- `key`: str - Attribute name
+- `value`: str - Attribute value to match
+
+**Returns:** HTMLElement or None
+
+#### first() → Optional[HTMLElement]
+Returns first child.
+
+```python
+first = div.first()
+```
+
+**Returns:** HTMLElement or None
+
+#### last() → Optional[HTMLElement]
+Returns last child.
+
+```python
+last = div.last()
+```
+
+**Returns:** HTMLElement or None
+
+#### count_children() → int
+Returns number of direct children.
+
+```python
+count = div.count_children()
+```
+
+**Returns:** int
+
+### Modifying Children
+
+#### replace_child(index: int, new_child: HTMLElement) → self
+Replaces child at index with new child.
+
+```python
+div.replace_child(0, H1("New Title"))
+```
+
+**Parameters:**
+- `index`: int - Index of child to replace
+- `new_child`: HTMLElement - New child element
+
+**Returns:** self (for chaining)
+
+---
+
+## Attribute Management Methods
+
+### add_attribute(key: str, value: str) → self
+Adds or updates single attribute.
+
+```python
+div.add_attribute("id", "main")
+div.add_attribute("data-value", "123")
+```
+
+**Parameters:**
+- `key`: str - Attribute name
+- `value`: str - Attribute value
+
+**Returns:** self (for chaining)
+
+### add_attributes(attributes: List[Tuple[str, str]]) → self
+Adds multiple attributes at once.
+
+```python
+div.add_attributes([
+    ("id", "main"),
+    ("class", "container"),
+    ("role", "main")
+])
+```
+
+**Parameters:**
+- `attributes`: List[Tuple[str, str]] - List of (key, value) tuples
+
+**Returns:** self (for chaining)
+
+### remove_attribute(key: str) → self
+Removes an attribute.
+
+```python
+div.remove_attribute("data-old")
+```
+
+**Parameters:**
+- `key`: str - Attribute name to remove
+
+**Returns:** self (for chaining)
+
+### get_attribute(key: str) → Optional[str]
+Gets attribute value.
+
+```python
+id_value = div.get_attribute("id")
+class_name = div.get_attribute("class_name")
+```
+
+**Parameters:**
+- `key`: str - Attribute name
+
+**Returns:** str or None
+
+### has_attribute(key: str) → bool
+Checks if attribute exists.
+
+```python
+if div.has_attribute("id"):
+    print("Has ID")
+```
+
+**Parameters:**
+- `key`: str - Attribute name
+
+**Returns:** bool
+
+### get_attributes(*keys: str) → Dict[str, str]
+Gets multiple attributes or all attributes.
+
+```python
+all_attrs = div.get_attributes()
+some_attrs = div.get_attributes("id", "class_name")
+```
+
+**Parameters:**
+- `*keys`: str - Attribute names (if empty, returns all)
+
+**Returns:** Dict[str, str]
+
+### generate_id() → str
+Generates unique ID if element doesn't have one.
+
+```python
+element_id = div.generate_id()  # Returns existing or generates new
+```
+
+**Returns:** str - The element's ID
+
+---
+
+## CSS Style Management Methods
+
+### add_style(key: str, value: str) → self
+Adds or updates single inline style.
+
+```python
+div.add_style("color", "red")
+div.add_style("font-size", "16px")
+```
+
+**Parameters:**
+- `key`: str - CSS property name (kebab-case or camelCase)
+- `value`: str - CSS property value
+
+**Returns:** self (for chaining)
+
+### add_styles(styles: Dict[str, str]) → self
+Adds multiple inline styles at once.
+
+```python
+div.add_styles({
+    "color": "blue",
+    "background-color": "#f0f0f0",
+    "padding": "20px",
+    "margin": "10px"
+})
+```
+
+**Parameters:**
+- `styles`: Dict[str, str] - Dictionary of CSS property: value pairs
+
+**Returns:** self (for chaining)
+
+### get_style(key: str) → Optional[str]
+Gets value of specific inline style.
+
+```python
+color = div.get_style("color")
+padding = div.get_style("padding")
+```
+
+**Parameters:**
+- `key`: str - CSS property name
+
+**Returns:** str or None
+
+### remove_style(key: str) → self
+Removes specific inline style.
+
+```python
+div.remove_style("margin")
+```
+
+**Parameters:**
+- `key`: str - CSS property name to remove
+
+**Returns:** self (for chaining)
+
+---
+
+## Rendering Methods
+
+### render(pretty: bool = False, _indent: int = 0) → str
+Renders element to HTML string.
+
+```python
+# Compact (default)
+html = div.render()
+# <div><h1>Title</h1><p>Content</p></div>
+
+# Pretty (indented)
+html = div.render(pretty=True)
+# <div>
+#   <h1>Title</h1>
+#   <p>Content</p>
+# </div>
+```
+
+**Parameters:**
+- `pretty`: bool (default: False) - Enable pretty printing with indentation
+- `_indent`: int (default: 0) - Internal parameter for indentation level
+
+**Returns:** str - HTML string
+
+**Note:** `_indent` is for internal use. Don't set it manually.
+
+### __str__() → str
+String representation (calls render() with pretty=False).
+
+```python
+html = str(div)
+# Same as: html = div.render()
+```
+
+**Returns:** str - Compact HTML string
+
+---
+
+## Serialization Methods
+
+### to_dict() → Dict
+Converts element to dictionary representation.
+
+```python
+data = div.to_dict()
+# {
+#     "tag": "div",
+#     "self_closing": False,
+#     "attributes": {"id": "main"},
+#     "text": "",
+#     "children": [...]
+# }
+```
+
+**Returns:** Dict with keys:
+- `tag`: str
+- `self_closing`: bool
+- `attributes`: Dict[str, str]
+- `text`: str
+- `children`: List[Dict]
+
+### to_json(indent: Optional[int] = None) → str
+Converts element to JSON string.
+
+```python
+# Compact JSON
+json_str = div.to_json()
+
+# Pretty JSON
+json_str = div.to_json(indent=2)
+```
+
+**Parameters:**
+- `indent`: Optional[int] - Number of spaces for indentation (None = compact)
+
+**Returns:** str - JSON string
+
+### from_dict(data: Dict) → HTMLElement (classmethod)
+Creates element from dictionary.
+
+```python
+data = {
+    "tag": "div",
+    "self_closing": False,
+    "attributes": {"id": "main"},
+    "text": "Content",
+    "children": []
+}
+element = HTMLElement.from_dict(data)
+```
+
+**Parameters:**
+- `data`: Dict - Dictionary with element data
+
+**Returns:** HTMLElement
+
+**Raises:**
+- `ValueError` if data is invalid or missing required fields
+
+### from_json(json_str: str) → HTMLElement (classmethod)
+Creates element from JSON string.
+
+```python
+json_str = '{"tag": "div", "text": "Hello", "children": []}'
+element = HTMLElement.from_json(json_str)
+```
+
+**Parameters:**
+- `json_str`: str - JSON string
+
+**Returns:** HTMLElement
+
+**Raises:**
+- `ValueError` if JSON is invalid
+
+### from_html(html_str: str, fragment: bool = False) → Union[HTMLElement, List[HTMLElement]] (classmethod)
+Parses HTML string to YDNATL element(s).
+
+```python
+# Single element
+element = HTMLElement.from_html('<div class="container">Content</div>')
+
+# Multiple root elements (fragment)
+elements = HTMLElement.from_html('<h1>Title</h1><p>Text</p>', fragment=True)
+```
+
+**Parameters:**
+- `html_str`: str - HTML string to parse
+- `fragment`: bool (default: False) - If True, returns list of elements
+
+**Returns:**
+- If `fragment=False`: HTMLElement or None
+- If `fragment=True`: List[HTMLElement]
+
+---
+
+## Parser Function
+
+### from_html(html_str: str, fragment: bool = False) → Union[HTMLElement, List[HTMLElement], None]
+
+**Location:** `ydnatl.core.parser.from_html` or `ydnatl.from_html`
+
+Standalone function for parsing HTML strings.
+
+```python
+from ydnatl import from_html
+
+# Parse single element
+element = from_html('<div>Content</div>')
+
+# Parse fragment
+elements = from_html('<h1>One</h1><p>Two</p>', fragment=True)
+```
+
+**Parameters:**
+- `html_str`: str - HTML string to parse
+- `fragment`: bool (default: False) - If True, returns list of elements
+
+**Returns:**
+- If `fragment=False`: HTMLElement or None
+- If `fragment=True`: List[HTMLElement]
+
+**Features:**
+- Handles all HTML5 elements
+- Converts `class` attribute to `class_name`
+- Preserves all attributes including data-*
+- Handles self-closing tags (br, img, hr, input, etc.)
+- Handles HTML entities (&amp;, &lt;, etc.)
+- Strips whitespace-only text nodes
+
+---
+
+## Utility Methods
+
+### clone() → HTMLElement
+Creates deep copy of element.
+
+```python
+original = Div(H1("Title"))
+copy = original.clone()
+# Modifying copy won't affect original
+```
+
+**Returns:** HTMLElement - Deep copy
+
+### __enter__() → self
+Enables use as context manager.
+
+```python
+with Div(id="container") as div:
+    div.append(H1("Title"))
+    div.append(Paragraph("Content"))
+```
+
+**Returns:** self
+
+### __exit__(exc_type, exc_val, exc_tb) → None
+Exits context manager.
+
+**Parameters:** Standard context manager parameters
+
+---
+
+## Event Callbacks
+
+### on_load() → None
+Called when element is loaded. Override in subclass.
+
+```python
+class MyElement(HTMLElement):
+    def on_load(self):
+        print("Element loaded")
+        # Custom initialization logic
+```
+
+### on_before_render() → None
+Called before element is rendered. Override in subclass.
+
+```python
+class MyElement(HTMLElement):
+    def on_before_render(self):
+        print("About to render")
+        # Pre-render logic
+```
+
+### on_after_render() → None
+Called after element is rendered. Override in subclass.
+
+```python
+class MyElement(HTMLElement):
+    def on_after_render(self):
+        print("Rendered")
+        # Post-render logic
+```
+
+### on_unload() → None
+Called when element is unloaded. Override in subclass.
+
+```python
+class MyElement(HTMLElement):
+    def on_unload(self):
+        print("Element unloaded")
+        # Cleanup logic
+```
+
+---
+
+## Fragment Class
+
+**Location:** `ydnatl.core.fragment.Fragment`
+
+Special element that renders only its children without a wrapper tag.
+
+### Constructor
+
+```python
+Fragment(*children, **kwargs)
+```
+
+**Note:** Any attributes passed are ignored (Fragment doesn't render a tag).
+
+### Usage
+
+```python
+from ydnatl import Fragment, H1, Paragraph
+
+# Without Fragment - adds wrapper
+content = Div(H1("Title"), Paragraph("Text"))
+# Output: <div><h1>Title</h1><p>Text</p></div>
+
+# With Fragment - no wrapper
+content = Fragment(H1("Title"), Paragraph("Text"))
+# Output: <h1>Title</h1><p>Text</p>
+```
+
+### Methods
+Inherits all methods from HTMLElement.
+
+**Important:** `render()` outputs only children without wrapper tags.
+
+---
+
+## Tag Classes by Module
+
+All tag classes follow the same constructor pattern as HTMLElement:
+
+```python
+TagName(*children, **attributes)
+```
+
+### ydnatl.tags.text
+
+**Headings:**
+- `H1(*children, **attributes)`
+- `H2(*children, **attributes)`
+- `H3(*children, **attributes)`
+- `H4(*children, **attributes)`
+- `H5(*children, **attributes)`
+- `H6(*children, **attributes)`
+
+**Text Elements:**
+- `Paragraph(*children, **attributes)` - `<p>`
+- `Span(*children, **attributes)` - `<span>`
+- `Bold(*children, **attributes)` - `<b>`
+- `Strong(*children, **attributes)` - `<strong>`
+- `Italic(*children, **attributes)` - `<i>`
+- `Em(*children, **attributes)` - `<em>`
+- `Underline(*children, **attributes)` - `<u>`
+- `Strikethrough(*children, **attributes)` - `<s>`
+- `Small(*children, **attributes)` - `<small>`
+- `Mark(*children, **attributes)` - `<mark>`
+- `Del(*children, **attributes)` - `<del>`
+- `Ins(*children, **attributes)` - `<ins>`
+- `Subscript(*children, **attributes)` - `<sub>`
+- `Superscript(*children, **attributes)` - `<sup>`
+
+**Code/Technical:**
+- `Code(*children, **attributes)` - `<code>`
+- `Pre(*children, **attributes)` - `<pre>`
+- `Kbd(*children, **attributes)` - `<kbd>`
+- `Samp(*children, **attributes)` - `<samp>`
+- `Var(*children, **attributes)` - `<var>`
+
+**Semantic:**
+- `Blockquote(*children, **attributes)` - `<blockquote>`
+- `Quote(*children, **attributes)` - `<q>`
+- `Cite(*children, **attributes)` - `<cite>`
+- `Abbr(*children, **attributes)` - `<abbr>`
+- `Dfn(*children, **attributes)` - `<dfn>`
+- `Time(*children, **attributes)` - `<time>`
+
+**Links & Line Breaks:**
+- `Link(*children, **attributes)` - `<a>`
+- `Br(**attributes)` - `<br>` (self-closing)
+- `Wbr(**attributes)` - `<wbr>` (self-closing)
+
+### ydnatl.tags.layout
+
+- `Div(*children, **attributes)` - `<div>`
+- `Section(*children, **attributes)` - `<section>`
+- `Article(*children, **attributes)` - `<article>`
+- `Aside(*children, **attributes)` - `<aside>`
+- `Header(*children, **attributes)` - `<header>`
+- `Footer(*children, **attributes)` - `<footer>`
+- `Nav(*children, **attributes)` - `<nav>`
+- `Main(*children, **attributes)` - `<main>`
+- `HorizontalRule(**attributes)` - `<hr>` (self-closing)
+- `Details(*children, **attributes)` - `<details>`
+- `Summary(*children, **attributes)` - `<summary>`
+- `Dialog(*children, **attributes)` - `<dialog>`
+
+### ydnatl.tags.form
+
+- `Form(*children, **attributes)` - `<form>`
+- `Input(**attributes)` - `<input>` (self-closing)
+- `Textarea(*children, **attributes)` - `<textarea>`
+- `Button(*children, **attributes)` - `<button>`
+- `Label(*children, **attributes)` - `<label>`
+- `Select(*children, **attributes)` - `<select>`
+- `Option(*children, **attributes)` - `<option>`
+- `Optgroup(*children, **attributes)` - `<optgroup>`
+- `Fieldset(*children, **attributes)` - `<fieldset>`
+- `Legend(*children, **attributes)` - `<legend>`
+- `Output(*children, **attributes)` - `<output>`
+- `Progress(*children, **attributes)` - `<progress>`
+- `Meter(*children, **attributes)` - `<meter>`
+
+### ydnatl.tags.lists
+
+- `UnorderedList(*children, **attributes)` - `<ul>`
+- `OrderedList(*children, **attributes)` - `<ol>`
+- `ListItem(*children, **attributes)` - `<li>`
+- `Datalist(*children, **attributes)` - `<datalist>`
+- `DescriptionList(*children, **attributes)` - `<dl>`
+- `DescriptionTerm(*children, **attributes)` - `<dt>`
+- `DescriptionDetails(*children, **attributes)` - `<dd>`
+
+### ydnatl.tags.table
+
+- `Table(*children, **attributes)` - `<table>`
+- `TableHeader(*children, **attributes)` - `<thead>`
+- `TableBody(*children, **attributes)` - `<tbody>`
+- `TableFooter(*children, **attributes)` - `<tfoot>`
+- `TableRow(*children, **attributes)` - `<tr>`
+- `TableHeaderCell(*children, **attributes)` - `<th>`
+- `TableDataCell(*children, **attributes)` - `<td>`
+- `Caption(*children, **attributes)` - `<caption>`
+- `Colgroup(*children, **attributes)` - `<colgroup>`
+- `Col(**attributes)` - `<col>` (self-closing)
+
+**Special Table Methods:**
+
+#### Table.from_json(file_path: str, **table_attrs)
+Creates table from JSON file.
+
+```python
+table = Table.from_json("data.json", class_name="data-table")
+```
+
+**JSON Format:**
+```json
+{
+  "headers": ["Name", "Age", "City"],
+  "rows": [
+    ["Alice", "30", "NYC"],
+    ["Bob", "25", "LA"]
+  ]
+}
+```
+
+#### Table.from_csv(file_path: str, **table_attrs)
+Creates table from CSV file.
+
+```python
+table = Table.from_csv("data.csv", class_name="data-table")
+```
+
+### ydnatl.tags.media
+
+- `Image(**attributes)` - `<img>` (self-closing)
+- `Video(*children, **attributes)` - `<video>`
+- `Audio(*children, **attributes)` - `<audio>`
+- `Source(**attributes)` - `<source>` (self-closing)
+- `Track(**attributes)` - `<track>` (self-closing)
+- `Picture(*children, **attributes)` - `<picture>`
+- `Figure(*children, **attributes)` - `<figure>`
+- `Figcaption(*children, **attributes)` - `<figcaption>`
+- `Canvas(*children, **attributes)` - `<canvas>`
+- `Embed(**attributes)` - `<embed>` (self-closing)
+- `Object(*children, **attributes)` - `<object>`
+- `Param(**attributes)` - `<param>` (self-closing)
+- `Map(*children, **attributes)` - `<map>`
+- `Area(**attributes)` - `<area>` (self-closing)
+
+### ydnatl.tags.html
+
+- `HTML(*children, **attributes)` - `<html>` (includes DOCTYPE)
+- `Head(*children, **attributes)` - `<head>`
+- `Body(*children, **attributes)` - `<body>`
+- `Title(*children, **attributes)` - `<title>`
+- `Meta(**attributes)` - `<meta>` (self-closing)
+- `Link(**attributes)` - `<link>` (self-closing)
+- `HtmlLink(**attributes)` - Alias for Link (avoid conflicts)
+- `Script(*children, **attributes)` - `<script>`
+- `Style(*children, **attributes)` - `<style>`
+- `Base(**attributes)` - `<base>` (self-closing)
+- `Noscript(*children, **attributes)` - `<noscript>`
+- `IFrame(*children, **attributes)` - `<iframe>`
+
+**Note:** `HTML` element automatically includes `<!DOCTYPE html>` in render output.
+
+---
+
+## Styling System (ydnatl.styles)
+
+**Location:** `ydnatl.styles`
+
+YDNATL includes a comprehensive styling system for managing external stylesheets, themes, and reusable component styles. This complements the existing inline style methods and is perfect for larger applications.
+
+### Key Features
+
+- **External Stylesheets**: Extract styles to `<style>` tags instead of inline
+- **BEM Support**: Built-in BEM naming convention (Block__Element--Modifier)
+- **Theming**: Pre-built themes (Modern, Classic, Minimal) with CSS variables
+- **Responsive**: Automatic media query generation with breakpoints
+- **Pseudo-selectors**: Support for :hover, :active, :focus, etc.
+- **JSON Serialization**: Save/load styles for website builders
+- **Compatible**: Works seamlessly with existing inline styles
+
+### Import Patterns
+
+```python
+# Import styling classes
+from ydnatl.styles import CSSStyle, StyleSheet, Theme
+
+# Or from main module
+from ydnatl import CSSStyle, StyleSheet, Theme
+```
+
+---
+
+## CSSStyle Class
+
+**Location:** `ydnatl.styles.CSSStyle`
+
+Represents CSS styles with support for pseudo-selectors and responsive breakpoints.
+
+### Constructor
+
+```python
+CSSStyle(**kwargs)
+```
+
+**Parameters:**
+- `**kwargs`: CSS properties as keyword arguments
+  - Use snake_case (converted to kebab-case automatically)
+  - Prefix with `_` for pseudo-selectors: `_hover`, `_active`, `_focus`
+  - Prefix with `_` for breakpoints: `_sm`, `_md`, `_lg`, `_xl`
+
+**Example:**
+```python
+style = CSSStyle(
+    background_color="#007bff",
+    color="white",
+    padding="10px 20px",
+    border_radius="5px",
+    _hover=CSSStyle(background_color="#0056b3"),
+    _md=CSSStyle(padding="15px 30px")
+)
+```
+
+### Properties
+
+| Property       | Type                      | Description                |
+|----------------|---------------------------|----------------------------|
+| `_styles`      | Dict[str, str]            | Base CSS properties        |
+| `_pseudo`      | Dict[str, CSSStyle]       | Pseudo-selector styles     |
+| `_breakpoints` | Dict[str, CSSStyle]       | Responsive breakpoint styles |
+
+### Methods
+
+#### to_inline() → str
+Generates inline style string (for `style="..."` attribute).
+
+```python
+style = CSSStyle(color="blue", padding="10px")
+inline = style.to_inline()
+# Returns: "color: blue; padding: 10px"
+```
+
+**Returns:** str - CSS string for inline styles
+
+**Note:** Only includes base styles, not pseudo-selectors or breakpoints.
+
+#### merge(other: CSSStyle) → CSSStyle
+Merges another CSSStyle, returning new CSSStyle. Other style overrides this one.
+
+```python
+base = CSSStyle(color="blue", padding="10px")
+override = CSSStyle(color="red", margin="5px")
+merged = base.merge(override)
+# Result: color="red", padding="10px", margin="5px"
+```
+
+**Parameters:**
+- `other`: CSSStyle - Style to merge
+
+**Returns:** CSSStyle - New merged style object
+
+#### has_pseudo_or_breakpoints() → bool
+Checks if style has pseudo-selectors or breakpoints.
+
+```python
+style = CSSStyle(color="blue", _hover=CSSStyle(color="red"))
+has_special = style.has_pseudo_or_breakpoints()  # True
+```
+
+**Returns:** bool
+
+#### is_complex(threshold: int = 3) → bool
+Checks if style is complex (has many properties).
+
+```python
+simple = CSSStyle(color="blue")
+simple.is_complex()  # False
+
+complex_style = CSSStyle(color="blue", padding="10px", margin="5px", border="1px solid")
+complex_style.is_complex()  # True
+```
+
+**Parameters:**
+- `threshold`: int (default: 3) - Number of properties considered complex
+
+**Returns:** bool
+
+#### to_dict() → Dict[str, Any]
+Serializes to JSON-compatible dictionary.
+
+```python
+style = CSSStyle(color="blue", _hover=CSSStyle(color="red"))
+data = style.to_dict()
+# Returns: {"styles": {"color": "blue"}, "pseudo": {"hover": {...}}, "breakpoints": {}}
+```
+
+**Returns:** Dict with keys:
+- `styles`: Dict[str, str]
+- `pseudo`: Dict[str, Dict] (if present)
+- `breakpoints`: Dict[str, Dict] (if present)
+
+#### from_dict(data: Dict[str, Any]) → CSSStyle (classmethod)
+Deserializes from dictionary.
+
+```python
+data = {"styles": {"color": "blue"}, "pseudo": {}, "breakpoints": {}}
+style = CSSStyle.from_dict(data)
+```
+
+**Parameters:**
+- `data`: Dict - Dictionary from to_dict()
+
+**Returns:** CSSStyle
+
+### Pseudo-selectors
+
+Supported pseudo-selectors (prefix with `_`):
+- `_hover` → `:hover`
+- `_active` → `:active`
+- `_focus` → `:focus`
+- `_visited` → `:visited`
+- `_link` → `:link`
+- `_first_child` → `:first-child`
+- `_last_child` → `:last-child`
+
+### Breakpoints
+
+Supported breakpoints (prefix with `_`):
+- `_xs` → 0px (default)
+- `_sm` → 640px
+- `_md` → 768px
+- `_lg` → 1024px
+- `_xl` → 1280px
+- `_2xl` → 1536px
+
+---
+
+## StyleSheet Class
+
+**Location:** `ydnatl.styles.StyleSheet`
+
+Manages CSS classes and generates `<style>` tag content.
+
+### Constructor
+
+```python
+StyleSheet(theme: Optional[Theme] = None)
+```
+
+**Parameters:**
+- `theme`: Optional[Theme] - Theme to include CSS variables
+
+**Example:**
+```python
+# Without theme
+stylesheet = StyleSheet()
+
+# With theme
+theme = Theme.modern()
+stylesheet = StyleSheet(theme=theme)
+```
+
+### Methods
+
+#### register(name: Optional[str] = None, style: Optional[CSSStyle] = None) → str
+Registers a style as a CSS class.
+
+```python
+stylesheet = StyleSheet()
+btn_class = stylesheet.register("btn-primary", CSSStyle(
+    background_color="#007bff",
+    color="white"
+))
+# Returns: "btn-primary"
+```
+
+**Parameters:**
+- `name`: Optional[str] - Class name (auto-generated if None)
+- `style`: Optional[CSSStyle] - Style to register
+
+**Returns:** str - Class name (for use in `class_name` attribute)
+
+#### register_bem(block: str, element: Optional[str] = None, modifier: Optional[str] = None, style: Optional[CSSStyle] = None) → str
+Registers a style using BEM naming convention.
+
+```python
+# Block
+card = stylesheet.register_bem("card", style=CSSStyle(padding="20px"))
+# Returns: "card"
+
+# Block + Element
+header = stylesheet.register_bem("card", element="header", style=CSSStyle(font_weight="bold"))
+# Returns: "card__header"
+
+# Block + Modifier
+featured = stylesheet.register_bem("card", modifier="featured", style=CSSStyle(border="2px solid blue"))
+# Returns: "card--featured"
+
+# Block + Element + Modifier
+icon = stylesheet.register_bem("card", element="icon", modifier="large", style=CSSStyle(font_size="24px"))
+# Returns: "card__icon--large"
+```
+
+**Parameters:**
+- `block`: str - Block name
+- `element`: Optional[str] - Element name
+- `modifier`: Optional[str] - Modifier name
+- `style`: Optional[CSSStyle] - Style to register
+
+**Returns:** str - BEM class name
+
+#### get_style(name: str) → Optional[CSSStyle]
+Gets a registered style by class name.
+
+```python
+style = stylesheet.get_style("btn-primary")
+```
+
+**Parameters:**
+- `name`: str - Class name
+
+**Returns:** CSSStyle or None
+
+#### has_class(name: str) → bool
+Checks if a class is registered.
+
+```python
+if stylesheet.has_class("btn-primary"):
+    print("Class exists")
+```
+
+**Parameters:**
+- `name`: str - Class name
+
+**Returns:** bool
+
+#### unregister(name: str) → bool
+Removes a registered class.
+
+```python
+success = stylesheet.unregister("old-class")
+```
+
+**Parameters:**
+- `name`: str - Class name to remove
+
+**Returns:** bool - True if removed, False if not found
+
+#### clear() → None
+Removes all registered classes.
+
+```python
+stylesheet.clear()
+```
+
+#### set_breakpoint(name: str, value: str) → None
+Sets or updates a breakpoint value.
+
+```python
+stylesheet.set_breakpoint("xl", "1440px")
+```
+
+**Parameters:**
+- `name`: str - Breakpoint name (e.g., "sm", "md")
+- `value`: str - CSS value (e.g., "640px")
+
+#### render(pretty: bool = True) → str
+Generates CSS output for all registered classes.
+
+```python
+css = stylesheet.render()
+# Returns full CSS string with classes, pseudo-selectors, and media queries
+```
+
+**Parameters:**
+- `pretty`: bool (default: True) - Format with newlines and indentation
+
+**Returns:** str - CSS string
+
+#### to_style_tag(pretty: bool = True) → str
+Generates a complete `<style>` tag with all CSS.
+
+```python
+tag = stylesheet.to_style_tag()
+# Returns: "<style>\n.btn-primary { ... }\n</style>"
+```
+
+**Parameters:**
+- `pretty`: bool (default: True) - Format with newlines
+
+**Returns:** str - HTML `<style>` tag with CSS
+
+#### count_classes() → int
+Gets the number of registered classes.
+
+```python
+count = stylesheet.count_classes()
+```
+
+**Returns:** int
+
+#### get_all_class_names() → List[str]
+Gets a list of all registered class names.
+
+```python
+names = stylesheet.get_all_class_names()
+# Returns: ["btn-primary", "card", "card__header", ...]
+```
+
+**Returns:** List[str]
+
+#### to_dict() → Dict
+Serializes stylesheet to dictionary.
+
+```python
+data = stylesheet.to_dict()
+# Returns: {"classes": {...}, "breakpoints": {...}}
+```
+
+**Returns:** Dict with keys:
+- `classes`: Dict[str, Dict]
+- `breakpoints`: Dict[str, str]
+
+#### from_dict(data: Dict, theme: Optional[Theme] = None) → StyleSheet (classmethod)
+Deserializes stylesheet from dictionary.
+
+```python
+stylesheet = StyleSheet.from_dict(data, theme=Theme.modern())
+```
+
+**Parameters:**
+- `data`: Dict - Dictionary from to_dict()
+- `theme`: Optional[Theme] - Theme to include
+
+**Returns:** StyleSheet
+
+---
+
+## Theme Class
+
+**Location:** `ydnatl.styles.Theme`
+
+Represents a design theme with colors, typography, spacing, and component styles.
+
+### Constructor
+
+```python
+Theme(
+    name: str = "Default",
+    colors: Optional[Dict[str, str]] = None,
+    typography: Optional[Dict[str, Any]] = None,
+    spacing: Optional[Dict[str, str]] = None,
+    components: Optional[Dict[str, Any]] = None
+)
+```
+
+**Parameters:**
+- `name`: str - Theme name
+- `colors`: Optional[Dict[str, str]] - Color palette
+- `typography`: Optional[Dict[str, Any]] - Font settings
+- `spacing`: Optional[Dict[str, str]] - Spacing scale
+- `components`: Optional[Dict[str, Any]] - Pre-styled components
+
+**Example:**
+```python
+theme = Theme(
+    name="Custom",
+    colors={
+        "primary": "#007bff",
+        "secondary": "#6c757d"
+    },
+    spacing={
+        "sm": "8px",
+        "md": "16px",
+        "lg": "24px"
+    }
+)
+```
+
+### Preset Themes (Class Methods)
+
+#### Theme.modern() → Theme
+Modern theme with clean, contemporary design.
+
+```python
+theme = Theme.modern()
+```
+
+**Returns:** Theme with:
+- Colors: Blue primary (#3b82f6), purple secondary
+- Typography: Inter, system fonts
+- Components: Modern buttons, cards
+
+#### Theme.classic() → Theme
+Classic theme with traditional, timeless design.
+
+```python
+theme = Theme.classic()
+```
+
+**Returns:** Theme with:
+- Colors: Traditional blue (#0066cc)
+- Typography: Georgia, serif fonts
+- Components: Classic buttons with borders
+
+#### Theme.minimal() → Theme
+Minimal theme with clean, stripped-down design.
+
+```python
+theme = Theme.minimal()
+```
+
+**Returns:** Theme with:
+- Colors: Black and white (#000000, #ffffff)
+- Typography: System fonts
+- Components: Minimal, flat buttons
+
+### Methods
+
+#### get_css_variables() → Dict[str, str]
+Generates CSS variables from theme properties.
+
+```python
+theme = Theme(colors={"primary": "#007bff"}, spacing={"md": "16px"})
+variables = theme.get_css_variables()
+# Returns: {"--color-primary": "#007bff", "--spacing-md": "16px"}
+```
+
+**Returns:** Dict[str, str] - CSS variable names and values
+
+#### get_component_style(component: str, variant: str = "default") → Optional[CSSStyle]
+Gets a component style from the theme.
+
+```python
+theme = Theme.modern()
+btn_style = theme.get_component_style("button", "primary")
+```
+
+**Parameters:**
+- `component`: str - Component name (e.g., "button", "card")
+- `variant`: str (default: "default") - Variant name (e.g., "primary", "secondary")
+
+**Returns:** CSSStyle or None
+
+#### to_dict() → Dict[str, Any]
+Serializes theme to dictionary.
+
+```python
+data = theme.to_dict()
+```
+
+**Returns:** Dict with keys:
+- `name`: str
+- `colors`: Dict[str, str]
+- `typography`: Dict[str, Any]
+- `spacing`: Dict[str, str]
+- `components`: Dict[str, Any]
+
+#### from_dict(data: Dict[str, Any]) → Theme (classmethod)
+Deserializes theme from dictionary.
+
+```python
+theme = Theme.from_dict(data)
+```
+
+**Parameters:**
+- `data`: Dict - Dictionary from to_dict()
+
+**Returns:** Theme
+
+---
+
+## Styling Patterns
+
+### Pattern 1: Basic StyleSheet Usage
+
+```python
+from ydnatl import HTML, Head, Body, Button, Style
+from ydnatl.styles import CSSStyle, StyleSheet
+
+# Create stylesheet
+stylesheet = StyleSheet()
+
+# Register button styles
+btn_primary = stylesheet.register("btn-primary", CSSStyle(
+    background_color="#007bff",
+    color="white",
+    padding="10px 20px",
+    border_radius="5px",
+    border="none",
+    cursor="pointer",
+    _hover=CSSStyle(background_color="#0056b3")
+))
+
+# Use in HTML
+page = HTML(
+    Head(Style(stylesheet.render())),
+    Body(
+        Button("Click Me", class_name=btn_primary),
+        Button("Another Button", class_name=btn_primary)
+    )
+)
+```
+
+### Pattern 2: Using Themes
+
+```python
+from ydnatl import HTML, Head, Body, Div, Button, Style
+from ydnatl.styles import Theme, StyleSheet, CSSStyle
+
+# Use preset theme
+theme = Theme.modern()
+stylesheet = StyleSheet(theme=theme)
+
+# Register styles using theme variables
+btn = stylesheet.register("btn", CSSStyle(
+    background_color="var(--color-primary)",
+    color="var(--color-white)",
+    padding="var(--spacing-md)",
+    border_radius="6px",
+    _hover=CSSStyle(background_color="var(--color-primary-dark)")
+))
+
+card = stylesheet.register("card", CSSStyle(
+    background_color="var(--color-white)",
+    padding="var(--spacing-lg)",
+    border_radius="8px"
+))
+
+# Use in HTML
+page = HTML(
+    Head(Style(stylesheet.render())),
+    Body(
+        Div(
+            Button("Themed Button", class_name=btn),
+            class_name=card
+        )
+    )
+)
+```
+
+### Pattern 3: BEM Naming
+
+```python
+from ydnatl import Div
+from ydnatl.styles import StyleSheet, CSSStyle
+
+stylesheet = StyleSheet()
+
+# Register BEM classes
+card = stylesheet.register_bem("card", style=CSSStyle(
+    background="white",
+    padding="20px"
+))
+
+card_header = stylesheet.register_bem("card", element="header", style=CSSStyle(
+    font_weight="bold",
+    border_bottom="1px solid #ccc"
+))
+
+card_body = stylesheet.register_bem("card", element="body", style=CSSStyle(
+    padding="15px"
+))
+
+card_featured = stylesheet.register_bem("card", modifier="featured", style=CSSStyle(
+    border="2px solid blue"
+))
+
+# Use in HTML
+html = Div(
+    Div("Card Header", class_name=card_header),
+    Div("Card Body", class_name=card_body),
+    class_name=f"{card} {card_featured}"
+)
+```
+
+### Pattern 4: Responsive Styles
+
+```python
+from ydnatl.styles import StyleSheet, CSSStyle
+
+stylesheet = StyleSheet()
+
+# Register responsive container
+container = stylesheet.register("container", CSSStyle(
+    padding="10px",
+    margin="0 auto",
+    _sm=CSSStyle(padding="15px", max_width="640px"),
+    _md=CSSStyle(padding="20px", max_width="768px"),
+    _lg=CSSStyle(padding="30px", max_width="1024px")
+))
+
+# Generates:
+# .container { padding: 10px; margin: 0 auto; }
+# @media (min-width: 640px) { .container { padding: 15px; max-width: 640px; } }
+# @media (min-width: 768px) { .container { padding: 20px; max-width: 768px; } }
+# @media (min-width: 1024px) { .container { padding: 30px; max-width: 1024px; } }
+```
+
+### Pattern 5: Combining with Inline Styles
+
+```python
+from ydnatl import Button
+from ydnatl.styles import StyleSheet, CSSStyle
+
+stylesheet = StyleSheet()
+
+# Register base button style
+btn = stylesheet.register("btn", CSSStyle(
+    padding="10px 20px",
+    border_radius="5px",
+    border="none"
+))
+
+# Use base class + inline overrides
+button1 = Button("Blue Button", class_name=btn).add_styles({
+    "background-color": "#007bff",
+    "color": "white"
+})
+
+button2 = Button("Green Button", class_name=btn).add_styles({
+    "background-color": "#28a745",
+    "color": "white"
+})
+
+# Both buttons share base styles but have different colors
+```
+
+### Pattern 6: Serialization for Website Builders
+
+```python
+from ydnatl.styles import StyleSheet, CSSStyle
+import json
+
+# Create and populate stylesheet
+stylesheet = StyleSheet()
+stylesheet.register("btn", CSSStyle(color="blue", padding="10px"))
+stylesheet.register("card", CSSStyle(background="white", padding="20px"))
+
+# Save to JSON
+data = stylesheet.to_dict()
+json_str = json.dumps(data, indent=2)
+# Store in database, file, etc.
+
+# Later... load from JSON
+loaded_data = json.loads(json_str)
+restored_stylesheet = StyleSheet.from_dict(loaded_data)
+
+# Use restored stylesheet
+css = restored_stylesheet.render()
+```
+
+### Pattern 7: Custom Component with Styles
+
+```python
+from ydnatl import HTMLElement, Div, H2, Paragraph
+from ydnatl.styles import StyleSheet, CSSStyle
+
+class StyledCard(HTMLElement):
+    def __init__(self, title, content, stylesheet, **kwargs):
+        super().__init__(tag="div", **kwargs)
+
+        # Register card styles if not already registered
+        if not stylesheet.has_class("card"):
+            card_style = CSSStyle(
+                background="white",
+                padding="20px",
+                border_radius="8px",
+                box_shadow="0 2px 4px rgba(0,0,0,0.1)"
+            )
+            self.card_class = stylesheet.register("card", card_style)
+        else:
+            self.card_class = "card"
+
+        # Set class and append children
+        self.add_attribute("class_name", self.card_class)
+        self.append(
+            H2(title, class_name="card-title"),
+            Paragraph(content, class_name="card-content")
+        )
+
+# Usage
+stylesheet = StyleSheet()
+card1 = StyledCard("Title 1", "Content 1", stylesheet)
+card2 = StyledCard("Title 2", "Content 2", stylesheet)
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Building a Complete Page
+
+```python
+from ydnatl import HTML, Head, Body, Title, Meta, Div, H1, Paragraph
+
+page = HTML(
+    Head(
+        Title("My Page"),
+        Meta(charset="utf-8"),
+        Meta(name="viewport", content="width=device-width, initial-scale=1")
+    ),
+    Body(
+        Div(
+            H1("Welcome"),
+            Paragraph("This is my page."),
+            class_name="container"
+        )
+    )
+)
+
+html_string = page.render(pretty=True)
+```
+
+### Pattern 2: Dynamic Content with Conditionals
+
+```python
+from ydnatl import Div, H1, Paragraph
+
+def create_section(title, content, show_header=True):
+    section = Div(class_name="section")
+
+    if show_header:
+        section.append(H1(title))
+
+    section.append(Paragraph(content))
+
+    return section
+
+# Usage
+section = create_section("About", "Some content", show_header=True)
+```
+
+### Pattern 3: Lists with Iteration
+
+```python
+from ydnatl import UnorderedList, ListItem
+
+items = ["Apple", "Banana", "Orange"]
+
+ul = UnorderedList()
+for item in items:
+    ul.append(ListItem(item))
+
+# Or using Fragment
+from ydnatl import Fragment
+
+fragment = Fragment()
+for item in items:
+    fragment.append(ListItem(item))
+
+ul = UnorderedList(fragment)
+```
+
+### Pattern 4: Method Chaining
+
+```python
+from ydnatl import Div, H1, Paragraph
+
+container = (Div()
+    .add_attribute("id", "main")
+    .add_attribute("class_name", "container")
+    .add_style("padding", "20px")
+    .add_style("margin", "0 auto")
+    .append(H1("Title"))
+    .append(Paragraph("Content"))
+)
+```
+
+### Pattern 5: Context Managers
+
+```python
+from ydnatl import Div, Section, H1, Paragraph
+
+with Div(id="container") as container:
+    with Section(class_name="content") as section:
+        section.append(H1("Title"))
+        section.append(Paragraph("Content"))
+
+    container.append(section)
+
+html = container.render()
+```
+
+### Pattern 6: Forms
+
+```python
+from ydnatl import Form, Label, Input, Button
+
+form = Form(action="/submit", method="post")
+form.append(
+    Label("Name:", for_="name"),
+    Input(type="text", id="name", name="name", required=True),
+    Button("Submit", type="submit")
+)
+```
+
+### Pattern 7: Tables from Data
+
+```python
+from ydnatl import Table, TableHeader, TableBody, TableRow
+from ydnatl import TableHeaderCell, TableDataCell
+
+data = [
+    {"name": "Alice", "age": 30},
+    {"name": "Bob", "age": 25}
+]
+
+table = Table()
+
+# Header
+thead = TableHeader()
+header_row = TableRow()
+header_row.append(TableHeaderCell("Name"), TableHeaderCell("Age"))
+thead.append(header_row)
+table.append(thead)
+
+# Body
+tbody = TableBody()
+for row in data:
+    tr = TableRow()
+    tr.append(TableDataCell(row["name"]), TableDataCell(str(row["age"])))
+    tbody.append(tr)
+table.append(tbody)
+```
+
+### Pattern 8: Parsing and Modifying HTML
+
+```python
+from ydnatl import from_html
+
+# Parse existing HTML
+html_str = '<div class="old"><h1>Title</h1></div>'
+element = from_html(html_str)
+
+# Modify it
+element.add_attribute("class_name", "new")
+element.add_style("padding", "20px")
+element.append(Paragraph("New content"))
+
+# Render modified version
+new_html = element.render()
+```
+
+### Pattern 9: Serialization for Storage
+
+```python
+from ydnatl import Div, H1, Paragraph, HTMLElement
+
+# Create element tree
+page = Div(
+    H1("Title"),
+    Paragraph("Content"),
+    id="page"
+)
+
+# Save to JSON
+json_str = page.to_json(indent=2)
+# Store in database, file, etc.
+
+# Later... load from JSON
+loaded_page = HTMLElement.from_json(json_str)
+
+# Use it
+html = loaded_page.render()
+```
+
+### Pattern 10: Custom Components
+
+```python
+from ydnatl import HTMLElement, Div, H2, Paragraph
+
+class Card(HTMLElement):
+    def __init__(self, title, content, **kwargs):
+        super().__init__(
+            tag="div",
+            class_name="card",
+            **kwargs
+        )
+
+        self.append(
+            H2(title, class_name="card-title"),
+            Paragraph(content, class_name="card-content")
+        )
+
+    def on_before_render(self):
+        # Add shadow class if shadow attribute present
+        if self.has_attribute("shadow"):
+            current_class = self.get_attribute("class_name") or ""
+            self.add_attribute("class_name", f"{current_class} shadow")
+
+# Usage
+card = Card("My Card", "Card content", shadow="true")
+html = card.render()
+```
+
+---
+
+## Type Hints Reference
+
+When generating code with type hints:
+
+```python
+from typing import Optional, List, Dict, Union, Callable, Iterator, Tuple, Any
+
+# Constructor
+def __init__(
+    self,
+    *children: Union['HTMLElement', str],
+    tag: str = "div",
+    text: str = "",
+    self_closing: bool = False,
+    **attributes: str
+) -> None: ...
+
+# Element manipulation
+def append(self, *children: Union['HTMLElement', str]) -> 'HTMLElement': ...
+def prepend(self, *children: Union['HTMLElement', str]) -> 'HTMLElement': ...
+def clear(self) -> 'HTMLElement': ...
+def pop(self, index: int = -1) -> 'HTMLElement': ...
+def remove_all(self, condition: Callable[['HTMLElement'], bool]) -> 'HTMLElement': ...
+
+# Querying
+def filter(self, condition: Callable[['HTMLElement'], bool]) -> Iterator['HTMLElement']: ...
+def find_by_attribute(self, key: str, value: str) -> Optional['HTMLElement']: ...
+def first(self) -> Optional['HTMLElement']: ...
+def last(self) -> Optional['HTMLElement']: ...
+def count_children(self) -> int: ...
+
+# Attributes
+def add_attribute(self, key: str, value: str) -> 'HTMLElement': ...
+def add_attributes(self, attributes: List[Tuple[str, str]]) -> 'HTMLElement': ...
+def remove_attribute(self, key: str) -> 'HTMLElement': ...
+def get_attribute(self, key: str) -> Optional[str]: ...
+def has_attribute(self, key: str) -> bool: ...
+def get_attributes(self, *keys: str) -> Dict[str, str]: ...
+
+# Styles
+def add_style(self, key: str, value: str) -> 'HTMLElement': ...
+def add_styles(self, styles: Dict[str, str]) -> 'HTMLElement': ...
+def get_style(self, key: str) -> Optional[str]: ...
+def remove_style(self, key: str) -> 'HTMLElement': ...
+
+# Rendering
+def render(self, pretty: bool = False, _indent: int = 0) -> str: ...
+def __str__(self) -> str: ...
+
+# Serialization
+def to_dict(self) -> Dict[str, Any]: ...
+def to_json(self, indent: Optional[int] = None) -> str: ...
+
+@classmethod
+def from_dict(cls, data: Dict[str, Any]) -> 'HTMLElement': ...
+
+@classmethod
+def from_json(cls, json_str: str) -> 'HTMLElement': ...
+
+@classmethod
+def from_html(cls, html_str: str, fragment: bool = False) -> Union['HTMLElement', List['HTMLElement'], None]: ...
+
+# Utility
+def clone(self) -> 'HTMLElement': ...
+def replace_child(self, index: int, new_child: 'HTMLElement') -> 'HTMLElement': ...
+def generate_id(self) -> str: ...
+
+# Context manager
+def __enter__(self) -> 'HTMLElement': ...
+def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
+```
+
+---
+
+## Error Handling
+
+### Common Errors and Solutions
+
+**ValueError: Invalid JSON**
+```python
+try:
+    element = HTMLElement.from_json(json_str)
+except ValueError as e:
+    print(f"Invalid JSON: {e}")
+```
+
+**ValueError: Missing required field in dict**
+```python
+try:
+    element = HTMLElement.from_dict(data)
+except ValueError as e:
+    print(f"Invalid data: {e}")
+```
+
+**IndexError: pop from empty list**
+```python
+if div.count_children() > 0:
+    child = div.pop()
+else:
+    print("No children to pop")
+```
+
+**KeyError: Attribute not found**
+```python
+# Don't do this:
+value = div.attributes["missing"]  # KeyError
+
+# Do this instead:
+value = div.get_attribute("missing")  # Returns None
+if value is None:
+    print("Attribute not found")
+```
+
+---
+
+## Performance Considerations
+
+### Best Practices
+
+1. **Use method chaining for multiple operations**
+   ```python
+   # Good
+   div.add_attribute("id", "main").add_style("padding", "20px").append(child)
+
+   # Less efficient (but still fine)
+   div.add_attribute("id", "main")
+   div.add_style("padding", "20px")
+   div.append(child)
+   ```
+
+2. **Batch add children**
+   ```python
+   # Good
+   div.append(child1, child2, child3)
+
+   # Less efficient
+   div.append(child1)
+   div.append(child2)
+   div.append(child3)
+   ```
+
+3. **Use compact rendering for production**
+   ```python
+   # Production (smaller output)
+   html = element.render()
+
+   # Development only (larger output)
+   html = element.render(pretty=True)
+   ```
+
+4. **Reuse elements via cloning**
+   ```python
+   template = Div(H1("Title"), class_name="card")
+   card1 = template.clone()
+   card2 = template.clone()
+   ```
+
+---
+
+## Security Considerations
+
+### HTML Escaping
+
+YDNATL automatically escapes HTML entities in:
+- Text content
+- Attribute values
+
+```python
+# Safe - automatically escaped
+div = Div("<script>alert('xss')</script>")
+# Renders as: <div>&lt;script&gt;alert('xss')&lt;/script&gt;</div>
+
+# Safe - attribute values escaped
+div = Div(data_value='<script>alert("xss")</script>')
+# Renders as: <div data-value="&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"></div>
+```
+
+### No Raw HTML Injection
+
+YDNATL does not support raw HTML injection. All content is escaped. This prevents XSS attacks.
+
+---
+
+## Complete Example: Blog Post Page
+
+```python
+from ydnatl import (
+    HTML, Head, Body, Title, Meta, HtmlLink,
+    Div, Section, Article, Header, Footer, Nav,
+    H1, H2, Paragraph, Link, UnorderedList, ListItem
+)
+
+def create_blog_post(title, author, date, content):
+    return Article(
+        Header(
+            H1(title, class_name="post-title"),
+            Paragraph(
+                f"By {author} on {date}",
+                class_name="post-meta"
+            )
+        ),
+        Paragraph(content, class_name="post-content"),
+        class_name="blog-post"
+    )
+
+def create_page(posts):
+    page = HTML(
+        Head(
+            Title("My Blog"),
+            Meta(charset="utf-8"),
+            Meta(name="viewport", content="width=device-width, initial-scale=1"),
+            HtmlLink(rel="stylesheet", href="/style.css")
+        ),
+        Body(
+            Header(
+                H1("My Blog", class_name="site-title"),
+                Nav(
+                    UnorderedList(
+                        ListItem(Link("Home", href="/")),
+                        ListItem(Link("About", href="/about")),
+                        ListItem(Link("Contact", href="/contact"))
+                    )
+                )
+            ),
+            Section(
+                *[create_blog_post(
+                    post["title"],
+                    post["author"],
+                    post["date"],
+                    post["content"]
+                ) for post in posts],
+                class_name="posts"
+            ),
+            Footer(
+                Paragraph("© 2024 My Blog. All rights reserved.")
+            )
+        )
+    )
+
+    return page.render(pretty=True)
+
+# Usage
+posts = [
+    {
+        "title": "First Post",
+        "author": "Alice",
+        "date": "2024-01-01",
+        "content": "This is my first blog post!"
+    },
+    {
+        "title": "Second Post",
+        "author": "Bob",
+        "date": "2024-01-02",
+        "content": "Another interesting post."
+    }
+]
+
+html = create_page(posts)
+print(html)
+```
+
+---
+
+## Quick Reference Cheat Sheet
+
+### Creating Elements
+```python
+# Basic element
+div = Div("text content")
+
+# With attributes
+div = Div("text", id="main", class_name="container")
+
+# Nested
+div = Div(
+    H1("Title"),
+    Paragraph("Content")
+)
+```
+
+### Modifying Elements
+```python
+div.append(Paragraph("New"))           # Add child
+div.prepend(H1("First"))               # Add at start
+div.add_attribute("id", "main")        # Add attribute
+div.add_style("color", "red")          # Add style
+div.clear()                            # Remove all children
+```
+
+### Querying Elements
+```python
+count = div.count_children()           # Count children
+first = div.first()                    # Get first child
+elem = div.find_by_attribute("id", "x") # Find by attribute
+filtered = list(div.filter(lambda e: e.tag == "p"))
+```
+
+### Rendering
+```python
+html = div.render()                    # Compact HTML
+html = div.render(pretty=True)         # Pretty HTML
+html = str(div)                        # Same as render()
+```
+
+### Serialization
+```python
+json_str = div.to_json(indent=2)       # To JSON
+dict_data = div.to_dict()              # To dict
+elem = HTMLElement.from_json(json_str) # From JSON
+elem = HTMLElement.from_dict(dict_data) # From dict
+elem = from_html("<div>...</div>")     # From HTML
+```
+
+### Common Tags
+```python
+# Text
+H1("Heading"), Paragraph("Text"), Span("Inline")
+
+# Layout
+Div(), Section(), Article(), Header(), Footer()
+
+# Forms
+Form(), Input(type="text"), Button("Click"), Label("Name:")
+
+# Lists
+UnorderedList(), OrderedList(), ListItem("Item")
+
+# Tables
+Table(), TableRow(), TableDataCell("Data")
+
+# Media
+Image(src="pic.jpg"), Video(src="vid.mp4")
+```
+
+---
+
+## End of LLM Guide
+
+This guide provides complete technical specifications for the YDNATL library. When generating code:
+
+1. Use the exact method signatures provided
+2. Follow the patterns demonstrated
+3. Remember that all modification methods return `self` for chaining
+4. HTML escaping is automatic - don't manually escape
+5. Use `from_html()` for parsing existing HTML
+6. Use `to_json()` / `from_json()` for persistence
+7. Use `Fragment` when you need multiple elements without wrapper
+8. All tag classes work the same way: `TagName(*children, **attributes)`
+
+For any edge cases not covered, refer to the core `HTMLElement` class - all tags inherit from it and work identically.
\ No newline at end of file
diff --git a/README.md b/README.md
index 968fd7c..df63f35 100644
--- a/README.md
+++ b/README.md
@@ -8,14 +8,17 @@ YDNATL (**Y**ou **D**on't **N**eed **A**nother **T**emplate **L**anguage) is a P
 - ✓ JSON serialization/deserialization for saving and loading UI structures
 - ✓ Pretty printing with indentation for readable HTML
 - ✓ CSS style helpers for easy inline styling
+- ✓ External stylesheet system with theming and BEM support
 - ✓ Method chaining for fluent interfaces
 - ✓ Context manager support for clean nesting
 - ✓ Fragment support for wrapper-free grouping
+- ✓ HTML parsing to convert raw HTML strings into YDNATL elements
 - ✓ Lightweight
 - ✓ Extremely fast
 - ✓ Fully customisable
 - ✓ Compose HTML efficiently
 - ✓ Lean & clean Python with no dependencies
+- ✓ LLM Compatible
 
 ## Requirements
 
@@ -187,6 +190,146 @@ div.remove_style("margin")
 # Result: <div style="color: blue; font-size: 16px; background-color: #f0f0f0; padding: 20px; border-radius: 5px">Styled content</div>
 ```
 
+### External Stylesheet and Theming
+
+YDNATL includes a powerful styling system for managing external stylesheets, themes, and reusable component styles. This is perfect for building larger applications where you want to separate styles from markup.
+
+#### Basic StyleSheet Usage
+
+```python
+from ydnatl import *
+from ydnatl.styles import CSSStyle, StyleSheet
+
+# Create a stylesheet
+stylesheet = StyleSheet()
+
+# Register reusable styles
+btn_primary = stylesheet.register("btn-primary", CSSStyle(
+    background_color="#007bff",
+    color="white",
+    padding="10px 20px",
+    border_radius="5px",
+    border="none",
+    cursor="pointer",
+    _hover=CSSStyle(background_color="#0056b3")  # Pseudo-selector
+))
+
+# Use in HTML
+page = HTML(
+    Head(
+        Title("My Page"),
+        Style(stylesheet.render())  # Insert generated CSS
+    ),
+    Body(
+        Button("Click Me", class_name=btn_primary)
+    )
+)
+```
+
+#### Theming Support
+
+YDNATL includes three preset themes (Modern, Classic, Minimal) with full CSS variable support:
+
+```python
+from ydnatl.styles import Theme, StyleSheet, CSSStyle
+
+# Use a preset theme
+theme = Theme.modern()  # or Theme.classic() or Theme.minimal()
+
+# Create stylesheet with theme
+stylesheet = StyleSheet(theme=theme)
+
+# Register styles using theme variables
+btn = stylesheet.register("btn", CSSStyle(
+    background_color="var(--color-primary)",
+    color="var(--color-white)",
+    padding="var(--spacing-md)",
+    border_radius="6px",
+    _hover=CSSStyle(background_color="var(--color-primary-dark)")
+))
+
+card = stylesheet.register("card", CSSStyle(
+    background_color="var(--color-white)",
+    padding="var(--spacing-lg)",
+    border_radius="8px",
+    box_shadow="0 1px 3px rgba(0, 0, 0, 0.1)"
+))
+```
+
+#### BEM Naming Convention
+
+Built-in support for BEM (Block Element Modifier) naming:
+
+```python
+from ydnatl.styles import StyleSheet, CSSStyle
+
+stylesheet = StyleSheet()
+
+# Register with BEM naming
+card = stylesheet.register_bem("card", style=CSSStyle(
+    background="white",
+    padding="20px"
+))
+
+card_header = stylesheet.register_bem("card", element="header", style=CSSStyle(
+    font_weight="bold"
+))
+
+card_featured = stylesheet.register_bem("card", modifier="featured", style=CSSStyle(
+    border="2px solid blue"
+))
+
+# Generates: .card, .card__header, .card--featured
+```
+
+#### Responsive Breakpoints
+
+Add responsive styles with breakpoint support:
+
+```python
+from ydnatl.styles import CSSStyle, StyleSheet
+
+stylesheet = StyleSheet()
+
+container = stylesheet.register("container", CSSStyle(
+    padding="10px",
+    _sm=CSSStyle(padding="15px", max_width="640px"),
+    _md=CSSStyle(padding="20px", max_width="768px"),
+    _lg=CSSStyle(padding="30px", max_width="1024px")
+))
+
+# Generates media queries automatically
+```
+
+#### Combining with Inline Styles
+
+You can mix stylesheet classes with inline style overrides:
+
+```python
+# Register base style
+btn = stylesheet.register("btn", CSSStyle(
+    padding="10px 20px",
+    border_radius="5px"
+))
+
+# Use base class + inline overrides
+Button("Custom", class_name=btn).add_styles({
+    "background-color": "#ff0000",
+    "font-size": "18px"
+})
+```
+
+**Key Features:**
+- Snake_case to kebab-case conversion (background_color → background-color)
+- Pseudo-selector support (:hover, :active, :focus, etc.)
+- Responsive breakpoints with media queries
+- Theme system with CSS variables
+- BEM naming convention support
+- JSON serialization for saving/loading styles
+- Combines seamlessly with existing inline styles
+
+See the [examples/stylesheet_example.py](examples/stylesheet_example.py) file for complete working examples.
+
 ### Method Chaining
 
 All builder methods return `self`, enabling fluent method chaining:
@@ -284,6 +427,76 @@ page = Div(
 - List composition and iteration
 - Cleaner component architecture
 
+### HTML Parsing
+
+YDNATL can parse raw HTML strings and convert them into YDNATL elements. This is useful for importing existing HTML, migrating from other tools, or working with HTML from external sources.
+
+```python
+from ydnatl import from_html, HTMLElement
+
+# Parse a single HTML element
+html_string = '<div class="container"><h1>Hello World</h1><p>Welcome to YDNATL</p></div>'
+element = from_html(html_string)
+
+# Now you can work with it like any YDNATL element
+element.add_style("padding", "20px")
+element.append(Paragraph("Added via YDNATL"))
+
+print(element.render())
+# Output: <div class="container" style="padding: 20px"><h1>Hello World</h1><p>Welcome to YDNATL</p><p>Added via YDNATL</p></div>
+
+# Alternative: use the class method
+element = HTMLElement.from_html(html_string)
+```
+
+**Parsing HTML fragments** (multiple root elements):
+
+```python
+from ydnatl import from_html
+
+# HTML with multiple root elements
+html_fragment = '''
+<h1>Welcome</h1>
+<p>First paragraph</p>
+<p>Second paragraph</p>
+'''
+
+# Parse as fragment (returns list of elements)
+elements = from_html(html_fragment, fragment=True)
+
+# Work with each element
+for el in elements:
+    print(el.tag, el.text)
+# Output:
+# h1 Welcome
+# p First paragraph
+# p Second paragraph
+
+# Combine with other YDNATL features
+container = Div()
+for el in elements:
+    container.append(el)
+
+print(container.render())
+# Output: <div><h1>Welcome</h1><p>First paragraph</p><p>Second paragraph</p></div>
+```
+
+**Features:**
+- Handles all HTML5 elements including self-closing tags (br, img, hr, etc.)
+- Preserves attributes, including data-* attributes
+- Converts `class` attribute to `class_name` automatically
+- Supports nested structures of any depth
+- Handles HTML entities and special characters
+- No external dependencies (uses Python's built-in html.parser)
+
+**Use cases:**
+- Import existing HTML into your website builder
+- Migrate from other HTML generation tools
+- Parse HTML templates from external sources
+- Convert HTML snippets to YDNATL for manipulation
+- Testing and validation workflows
+- Combining static HTML with dynamic YDNATL generation
+
 ### JSON Serialization
 
 YDNATL supports JSON serialization and deserialization, making it perfect for drag-and-drop website builders, saving UI states, or transmitting page structures over APIs.
@@ -324,7 +537,7 @@ The JSON format is simple and clean:
     "class": "container"
   },
   "text": "",
-  "children": [...]
+  "children": []
 }
 ```
 
@@ -349,6 +562,15 @@ The JSON format is simple and clean:
 - Creating frontends for headless platforms (CMS/CRM etc)
 - Applications requiring UI state serialization
 
+## LLM Guide
+
+For AI assistants and code generation tools, we provide a comprehensive technical reference in [LLM_GUIDE.md](LLM_GUIDE.md) with:
+- Complete API documentation with exact method signatures
+- Type hints and return values for all methods
+- 10 common patterns with code examples
+- Error handling and security best practices
+- Quick reference cheat sheet
+
 ## Examples
 
 ### FastAPI
@@ -467,6 +689,8 @@ pytest
 - `instance.to_json(indent=None)` - Serialize to JSON string
 - `HTMLElement.from_dict(data)` - Reconstruct from dictionary (class method)
 - `HTMLElement.from_json(json_str)` - Reconstruct from JSON string (class method)
+- `HTMLElement.from_html(html_str, fragment=False)` - Parse HTML string to YDNATL element(s) (class method)
+- `from_html(html_str, fragment=False)` - Parse HTML string to YDNATL element(s) (function)
 
 ## Events
 
diff --git a/examples/stylesheet_example.py b/examples/stylesheet_example.py
new file mode 100644
index 0000000..375e26d
--- /dev/null
+++ b/examples/stylesheet_example.py
@@ -0,0 +1,295 @@
+"""Example demonstrating the StyleSheet system in YDNATL."""
+
+from ydnatl import *
+from ydnatl.styles import CSSStyle, StyleSheet, Theme
+
+
+def basic_stylesheet_example():
+    """Basic example of using StyleSheet."""
+    print("=== Basic StyleSheet Example ===\n")
+
+    # Create stylesheet
+    stylesheet = StyleSheet()
+
+    # Register button styles
+    btn_primary = stylesheet.register(
+        "btn-primary",
+        CSSStyle(
+            background_color="#007bff",
+            color="white",
+            padding="10px 20px",
+            border_radius="5px",
+            border="none",
+            font_weight="600",
+            cursor="pointer",
+            _hover=CSSStyle(background_color="#0056b3"),
+        ),
+    )
+
+    btn_secondary = stylesheet.register(
+        "btn-secondary",
+        CSSStyle(
+            background_color="#6c757d",
+            color="white",
+            padding="10px 20px",
+            border_radius="5px",
+            border="none",
+            font_weight="600",
+            cursor="pointer",
+            _hover=CSSStyle(background_color="#5a6268"),
+        ),
+    )
+
+    # Create HTML using the registered classes
+    page = HTML(
+        Head(Title("StyleSheet Example"), Style(stylesheet.render())),
+        Body(
+            Div(
+                H1("Button Examples"),
+                Button("Primary Button", class_name=btn_primary),
+                Button("Secondary Button", class_name=btn_secondary),
+            )
+        ),
+    )
+
+    print(page.render(pretty=True))
+
+
+def theme_example():
+    """Example using preset themes."""
+    print("\n\n=== Theme Example ===\n")
+
+    # Use a preset theme
+    theme = Theme.modern()
+
+    # Create stylesheet with theme
+    stylesheet = StyleSheet(theme=theme)
+
+    # Register styles that use theme variables
+    btn = stylesheet.register(
+        "btn",
+        CSSStyle(
+            background_color="var(--color-primary)",
+            color="var(--color-white)",
+            padding="var(--spacing-md)",
+            border_radius="6px",
+            font_family="var(--font-body)",
+            border="none",
+            cursor="pointer",
+            _hover=CSSStyle(background_color="var(--color-primary-dark)"),
+        ),
+    )
+
+    card = stylesheet.register(
+        "card",
+        CSSStyle(
+            background_color="var(--color-white)",
+            padding="var(--spacing-lg)",
+            border_radius="8px",
+            box_shadow="0 1px 3px rgba(0, 0, 0, 0.1)",
+            margin="var(--spacing-md)",
+        ),
+    )
+
+    # Create HTML
+    page = HTML(
+        Head(Title("Theme Example"), Style(stylesheet.render())),
+        Body(
+            Div(
+                H2("Welcome"),
+                Paragraph("This card uses theme variables."),
+                Button("Click Me", class_name=btn),
+                class_name=card,
+            ),
+            Div(
+                H2("Another Card"),
+                Paragraph("Consistent styling across components."),
+                Button("Learn More", class_name=btn),
+                class_name=card,
+            ),
+        ),
+    )
+
+    print(page.render(pretty=True))
+
+
+def bem_example():
+    """Example using BEM naming convention."""
+    print("\n\n=== BEM Example ===\n")
+
+    stylesheet = StyleSheet()
+
+    # Register BEM styles
+    card = stylesheet.register_bem(
+        "card",
+        style=CSSStyle(
+            background="white",
+            border_radius="8px",
+            box_shadow="0 2px 4px rgba(0,0,0,0.1)",
+            overflow="hidden",
+        ),
+    )
+
+    card_header = stylesheet.register_bem(
+        "card",
+        element="header",
+        style=CSSStyle(
+            padding="20px",
+            background="#f8f9fa",
+            border_bottom="1px solid #dee2e6",
+            font_weight="bold",
+        ),
+    )
+
+    card_body = stylesheet.register_bem(
+        "card", element="body", style=CSSStyle(padding="20px")
+    )
+
+    card_footer = stylesheet.register_bem(
+        "card",
+        element="footer",
+        style=CSSStyle(
+            padding="20px", background="#f8f9fa", border_top="1px solid #dee2e6"
+        ),
+    )
+
+    card_featured = stylesheet.register_bem(
+        "card", modifier="featured", style=CSSStyle(border="3px solid #007bff")
+    )
+
+    # Create HTML using BEM classes
+    page = HTML(
+        Head(Title("BEM Example"), Style(stylesheet.render())),
+        Body(
+            H1("BEM Card Examples"),
+            # Regular card
+            Div(
+                Div("Card Header", class_name=card_header),
+                Div(Paragraph("Card body content goes here."), class_name=card_body),
+                Div("Card Footer", class_name=card_footer),
+                class_name=card,
+            ),
+            # Featured card
+            Div(
+                Div("Featured Card", class_name=card_header),
+                Div(
+                    Paragraph("This is a featured card with special styling."),
+                    class_name=card_body,
+                ),
+                Div("Footer", class_name=card_footer),
+                class_name=f"{card} {card_featured}",
+            ),
+        ),
+    )
+
+    print(page.render(pretty=True))
+
+
+def responsive_example():
+    """Example with responsive breakpoints."""
+    print("\n\n=== Responsive Example ===\n")
+
+    stylesheet = StyleSheet()
+
+    # Register responsive styles
+    container = stylesheet.register(
+        "container",
+        CSSStyle(
+            padding="10px",
+            margin="0 auto",
+            _sm=CSSStyle(padding="15px", max_width="640px"),
+            _md=CSSStyle(padding="20px", max_width="768px"),
+            _lg=CSSStyle(padding="30px", max_width="1024px"),
+        ),
+    )
+
+    grid = stylesheet.register(
+        "grid",
+        CSSStyle(
+            display="grid",
+            grid_template_columns="1fr",
+            gap="10px",
+            _md=CSSStyle(grid_template_columns="1fr 1fr"),
+            _lg=CSSStyle(grid_template_columns="1fr 1fr 1fr"),
+        ),
+    )
+
+    # Create HTML
+    page = HTML(
+        Head(
+            Title("Responsive Example"),
+            Meta(name="viewport", content="width=device-width, initial-scale=1.0"),
+            Style(stylesheet.render()),
+        ),
+        Body(
+            Div(
+                H1("Responsive Grid"),
+                Div(
+                    Div("Item 1"),
+                    Div("Item 2"),
+                    Div("Item 3"),
+                    Div("Item 4"),
+                    Div("Item 5"),
+                    Div("Item 6"),
+                    class_name=grid,
+                ),
+                class_name=container,
+            )
+        ),
+    )
+
+    print(page.render(pretty=True))
+
+
+def combined_with_inline_example():
+    """Example combining stylesheet classes with inline styles."""
+    print("\n\n=== Combined Stylesheet + Inline Example ===\n")
+
+    stylesheet = StyleSheet()
+
+    # Register base button style
+    btn = stylesheet.register(
+        "btn",
+        CSSStyle(
+            padding="10px 20px",
+            border_radius="5px",
+            border="none",
+            font_weight="600",
+            cursor="pointer",
+        ),
+    )
+
+    # Create HTML using both class and inline styles
+    page = HTML(
+        Head(Title("Combined Example"), Style(stylesheet.render())),
+        Body(
+            H1("Combining Stylesheet and Inline Styles"),
+            # Base class + inline override
+            Button("Blue Button", class_name=btn).add_styles(
+                {"background-color": "#007bff", "color": "white"}
+            ),
+            # Same base class, different inline styles
+            Button("Green Button", class_name=btn).add_styles(
+                {"background-color": "#28a745", "color": "white"}
+            ),
+            # Same base class, more inline overrides
+            Button("Large Red Button", class_name=btn).add_styles(
+                {
+                    "background-color": "#dc3545",
+                    "color": "white",
+                    "padding": "15px 30px",
+                    "font-size": "18px",
+                }
+            ),
+        ),
+    )
+
+    print(page.render(pretty=True))
+
+
+if __name__ == "__main__":
+    basic_stylesheet_example()
+    theme_example()
+    bem_example()
+    responsive_example()
+    combined_with_inline_example()
diff --git a/pyproject.toml b/pyproject.toml
index 6747909..aa721d5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ydnatl"
-version = "1.0.6"
+version = "1.0.7"
 description = "YDNATL is a Python library that lets you build HTML UI using simple Python classes."
 readme = "README.md"
 requires-python = ">=3.8"
diff --git a/src/ydnatl/__init__.py b/src/ydnatl/__init__.py
index 423a5b8..22b1b53 100644
--- a/src/ydnatl/__init__.py
+++ b/src/ydnatl/__init__.py
@@ -1,5 +1,6 @@
 from .core.element import HTMLElement
 from .core.fragment import Fragment
+from .core.parser import from_html
 from .tags.form import (
     Textarea,
     Select,
@@ -115,10 +116,20 @@
     Br,
     Wbr,
 )
+from .styles import (
+    CSSStyle,
+    StyleSheet,
+    Theme,
+)
 
 __all__ = [
     "HTMLElement",
     "Fragment",
+    "from_html",
+    # styles
+    "CSSStyle",
+    "StyleSheet",
+    "Theme",
     # form
     "Textarea",
     "Select",
diff --git a/src/ydnatl/core/fragment.py b/src/ydnatl/core/fragment.py
index 3d21c2f..461f170 100644
--- a/src/ydnatl/core/fragment.py
+++ b/src/ydnatl/core/fragment.py
@@ -1,4 +1,5 @@
 from typing import Union, List, Any
+
 from ydnatl.core.element import HTMLElement
 
 
diff --git a/src/ydnatl/core/parser.py b/src/ydnatl/core/parser.py
new file mode 100644
index 0000000..3260708
--- /dev/null
+++ b/src/ydnatl/core/parser.py
@@ -0,0 +1,134 @@
+"""HTML Parser for YDNATL - Convert raw HTML to YDNATL elements."""
+
+from html.parser import HTMLParser
+from typing import List, Optional, Union
+
+from ydnatl.core.element import HTMLElement
+
+
+class YDNATLHTMLParser(HTMLParser):
+    """Parse HTML and convert to YDNATL element tree."""
+
+    VOID_ELEMENTS = {
+        "area",
+        "base",
+        "br",
+        "col",
+        "embed",
+        "hr",
+        "img",
+        "input",
+        "link",
+        "meta",
+        "param",
+        "source",
+        "track",
+        "wbr",
+    }
+
+    def __init__(self):
+        super().__init__()
+        self.roots: List[HTMLElement] = []  # Support multiple roots for fragments
+        self.stack: List[HTMLElement] = []
+        self.current: Optional[HTMLElement] = None
+
+    def handle_starttag(self, tag: str, attrs: List[tuple]):
+        """Handle opening tags."""
+        attributes = {}
+        for key, value in attrs:
+            if key == "class":
+                attributes["class_name"] = value
+            else:
+                attributes[key.replace("-", "_")] = value if value is not None else ""
+
+        is_self_closing = tag in self.VOID_ELEMENTS
+
+        element = HTMLElement(tag=tag, self_closing=is_self_closing, **attributes)
+
+        if self.current is not None:
+            self.current.append(element)
+        else:
+            self.roots.append(element)
+
+        if not is_self_closing:
+            self.stack.append(element)
+            self.current = element
+
+    def handle_endtag(self, tag: str):
+        """Handle closing tags."""
+        if self.stack and self.stack[-1].tag == tag:
+            self.stack.pop()
+            self.current = self.stack[-1] if self.stack else None
+
+    def handle_data(self, data: str):
+        """Handle text content between tags."""
+        text = data.strip()
+        if text and self.current is not None:
+            if self.current.text:
+                self.current.text += text
+            else:
+                self.current.text = text
+
+    def parse_html(self, html_string: str) -> Optional[HTMLElement]:
+        """Parse HTML string and return root element."""
+        self.feed(html_string)
+        return self.roots[0] if self.roots else None
+
+    def parse_fragment(self, html_string: str) -> List[HTMLElement]:
+        """Parse HTML fragment and return list of elements."""
+        self.feed(html_string)
+        return self.roots
+
+
+def from_html(
+    html_string: str, fragment: bool = False
+) -> Union[HTMLElement, List[HTMLElement], None]:
+    """Parse HTML string and convert to YDNATL element(s).
+
+    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)
+
+    Returns:
+        HTMLElement if fragment=False, List[HTMLElement] if fragment=True
+
+    Example:
+        >>> from ydnatl.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())
+    """
+    parser = YDNATLHTMLParser()
+
+    if fragment:
+        return parser.parse_fragment(html_string)
+    else:
+        return parser.parse_html(html_string)
+
+
+# Add convenience method to HTMLElement
+def _from_html_classmethod(cls, html_string: str, fragment: bool = False):
+    """Parse HTML string and convert to HTMLElement(s).
+
+    This is a class method added to HTMLElement for convenience.
+
+    Args:
+        html_string: Raw HTML string to parse
+        fragment: If True, returns list of elements
+
+    Returns:
+        HTMLElement or List[HTMLElement]
+    """
+    return from_html(html_string, fragment=fragment)
+
+
+# Monkey-patch HTMLElement to add from_html class method
+HTMLElement.from_html = classmethod(_from_html_classmethod)
diff --git a/src/ydnatl/styles/__init__.py b/src/ydnatl/styles/__init__.py
new file mode 100644
index 0000000..7518989
--- /dev/null
+++ b/src/ydnatl/styles/__init__.py
@@ -0,0 +1,11 @@
+"""YDNATL Styles Module - External stylesheet and theming support."""
+
+from .style import CSSStyle
+from .stylesheet import StyleSheet
+from .theme import Theme
+
+__all__ = [
+    "CSSStyle",
+    "StyleSheet",
+    "Theme",
+]
diff --git a/src/ydnatl/styles/style.py b/src/ydnatl/styles/style.py
new file mode 100644
index 0000000..570d36f
--- /dev/null
+++ b/src/ydnatl/styles/style.py
@@ -0,0 +1,201 @@
+"""CSS Style class for YDNATL."""
+
+from typing import Dict, Any
+
+
+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")
+        )
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initialize a CSSStyle object.
+
+        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)
+        """
+        self._styles: Dict[str, str] = {}
+        self._pseudo: Dict[str, "CSSStyle"] = {}
+        self._breakpoints: Dict[str, "CSSStyle"] = {}
+
+        # Known pseudo-selectors
+        PSEUDO_SELECTORS = {
+            "_hover",
+            "_active",
+            "_focus",
+            "_visited",
+            "_link",
+            "_first_child",
+            "_last_child",
+            "_nth_child",
+            "_before",
+            "_after",
+        }
+
+        # Known breakpoints (can be extended)
+        BREAKPOINTS = {"_xs", "_sm", "_md", "_lg", "_xl", "_2xl"}
+
+        for key, value in kwargs.items():
+            if isinstance(value, CSSStyle):
+                # It's a nested style for pseudo-selector or breakpoint
+                if key in PSEUDO_SELECTORS:
+                    self._pseudo[key[1:].replace("_", "-")] = value
+                elif key in BREAKPOINTS:
+                    self._breakpoints[key[1:]] = value
+            else:
+                # Regular CSS property
+                self._styles[self._to_css_prop(key)] = str(value)
+
+    def _to_css_prop(self, prop: str) -> str:
+        """
+        Convert Python snake_case to CSS kebab-case.
+
+        Args:
+            prop: Property name in snake_case
+
+        Returns:
+            Property name in kebab-case
+        """
+        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.
+
+        Args:
+            other: Another CSSStyle object to merge
+
+        Returns:
+            New CSSStyle object with merged properties
+        """
+        merged = CSSStyle()
+        merged._styles = {**self._styles, **other._styles}
+        merged._pseudo = {**self._pseudo, **other._pseudo}
+        merged._breakpoints = {**self._breakpoints, **other._breakpoints}
+        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.
+
+        Returns:
+            CSS string suitable for inline styles
+        """
+        if not self._styles:
+            return ""
+        return "; ".join(f"{k}: {v}" for k, v in self._styles.items())
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize to JSON-compatible dictionary.
+
+        Returns:
+            Dictionary representation of the style
+        """
+        result = {"styles": self._styles}
+
+        if self._pseudo:
+            result["pseudo"] = {k: v.to_dict() for k, v in self._pseudo.items()}
+
+        if self._breakpoints:
+            result["breakpoints"] = {
+                k: v.to_dict() for k, v in self._breakpoints.items()
+            }
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CSSStyle":
+        """
+        Deserialize from dictionary.
+
+        Args:
+            data: Dictionary representation from to_dict()
+
+        Returns:
+            New CSSStyle object
+        """
+        style = cls()
+        style._styles = data.get("styles", {})
+
+        # Reconstruct pseudo-selectors
+        if "pseudo" in data:
+            for key, value in data["pseudo"].items():
+                style._pseudo[key] = cls.from_dict(value)
+
+        # Reconstruct breakpoints
+        if "breakpoints" in data:
+            for key, value in data["breakpoints"].items():
+                style._breakpoints[key] = cls.from_dict(value)
+
+        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.
+
+        Returns:
+            True if style has pseudo-selectors or breakpoints
+        """
+        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.
+
+        Args:
+            threshold: Number of properties to consider complex
+
+        Returns:
+            True if style has more properties than threshold
+        """
+        return len(self._styles) > threshold
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"CSSStyle({self.to_inline()})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality with another CSSStyle."""
+        if not isinstance(other, CSSStyle):
+            return False
+        return (
+            self._styles == other._styles
+            and self._pseudo == other._pseudo
+            and self._breakpoints == other._breakpoints
+        )
+
+    def __hash__(self) -> int:
+        """Make CSSStyle hashable for use in dictionaries."""
+        # Convert dicts to sorted tuples for hashing
+        styles_tuple = tuple(sorted(self._styles.items()))
+        return hash(styles_tuple)
diff --git a/src/ydnatl/styles/stylesheet.py b/src/ydnatl/styles/stylesheet.py
new file mode 100644
index 0000000..8a88da4
--- /dev/null
+++ b/src/ydnatl/styles/stylesheet.py
@@ -0,0 +1,316 @@
+"""StyleSheet class for managing CSS classes in YDNATL."""
+
+from typing import Dict, Optional, List
+
+from .style import CSSStyle
+
+
+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()
+    """
+
+    def __init__(self, theme: Optional["Theme"] = None):
+        """
+        Initialize StyleSheet.
+
+        Args:
+            theme: Optional Theme object to include CSS variables
+        """
+        self.theme = theme
+        self._classes: Dict[str, CSSStyle] = {}
+        self._counter = 0
+
+        # Default breakpoint values (can be customized)
+        self._breakpoint_values = {
+            "xs": "0px",
+            "sm": "640px",
+            "md": "768px",
+            "lg": "1024px",
+            "xl": "1280px",
+            "2xl": "1536px",
+        }
+
+    def register(
+        self, name: Optional[str] = None, style: Optional[CSSStyle] = None
+    ) -> str:
+        """
+        Register a style as a CSS class.
+
+        Args:
+            name: Optional class name. If not provided, auto-generates one.
+            style: CSSStyle object to register
+
+        Returns:
+            The class name (for use in class_name attribute)
+        """
+        if style is None:
+            style = CSSStyle()
+
+        # Generate class name if not provided
+        if name is None:
+            name = f"s-{self._counter}"
+            self._counter += 1
+
+        # Store the style
+        self._classes[name] = style
+
+        return name
+
+    def register_bem(
+        self,
+        block: str,
+        element: Optional[str] = None,
+        modifier: Optional[str] = None,
+        style: Optional[CSSStyle] = None,
+    ) -> str:
+        """
+        Register a style using BEM naming convention.
+
+        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
+
+        Returns:
+            The BEM class name
+        """
+        # Build BEM class name
+        class_name = block
+
+        if element:
+            class_name += f"__{element}"
+
+        if modifier:
+            class_name += f"--{modifier}"
+
+        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 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 name in self._classes
+
+    def unregister(self, name: str) -> bool:
+        """
+        Remove a registered class.
+
+        Args:
+            name: Class name to remove
+
+        Returns:
+            True if class was removed, False if not found
+        """
+        if name in self._classes:
+            del self._classes[name]
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Remove all registered classes."""
+        self._classes.clear()
+        self._counter = 0
+
+    def set_breakpoint(self, name: str, value: str) -> None:
+        """
+        Set or update a breakpoint value.
+
+        Args:
+            name: Breakpoint name (e.g., "sm", "md")
+            value: CSS value (e.g., "640px")
+        """
+        self._breakpoint_values[name] = value
+
+    def _render_class_styles(
+        self, class_name: str, style: CSSStyle, indent: int = 2
+    ) -> List[str]:
+        """
+        Render styles for a single class.
+
+        Args:
+            class_name: The CSS class name
+            style: The CSSStyle object
+            indent: Number of spaces for indentation
+
+        Returns:
+            List of CSS strings
+        """
+        css_lines = []
+        indent_str = " " * indent
+
+        # Base styles
+        if style._styles:
+            css_lines.append(f".{class_name} {{")
+            for prop, value in style._styles.items():
+                css_lines.append(f"{indent_str}{prop}: {value};")
+            css_lines.append("}")
+
+        # Pseudo-selectors
+        for pseudo, pseudo_style in style._pseudo.items():
+            if pseudo_style._styles:
+                css_lines.append(f".{class_name}:{pseudo} {{")
+                for prop, value in pseudo_style._styles.items():
+                    css_lines.append(f"{indent_str}{prop}: {value};")
+                css_lines.append("}")
+
+        # Responsive breakpoints
+        for breakpoint, bp_style in style._breakpoints.items():
+            if bp_style._styles:
+                min_width = self._breakpoint_values.get(breakpoint, "0px")
+                css_lines.append(f"@media (min-width: {min_width}) {{")
+                css_lines.append(f"{indent_str}.{class_name} {{")
+                for prop, value in bp_style._styles.items():
+                    css_lines.append(f"{indent_str}{indent_str}{prop}: {value};")
+                css_lines.append(f"{indent_str}}}")
+                css_lines.append("}")
+
+        return css_lines
+
+    def render(self, pretty: bool = True) -> str:
+        """
+        Generate CSS output for all registered classes.
+
+        Args:
+            pretty: If True, format with newlines and indentation
+
+        Returns:
+            CSS string
+        """
+        css_lines = []
+
+        # CSS variables from theme
+        if self.theme:
+            css_lines.append(":root {")
+            for key, value in self.theme.get_css_variables().items():
+                css_lines.append(f"  {key}: {value};")
+            css_lines.append("}")
+            if pretty:
+                css_lines.append("")  # Empty line for spacing
+
+        # Render all classes
+        for class_name, style in self._classes.items():
+            class_css = self._render_class_styles(class_name, style)
+            css_lines.extend(class_css)
+            if pretty:
+                css_lines.append("")  # Empty line between classes
+
+        # Join with newlines if pretty, otherwise compact
+        if pretty:
+            return "\n".join(css_lines).rstrip()
+        else:
+            # Compact format
+            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.
+
+        Args:
+            pretty: If True, format with newlines and indentation
+
+        Returns:
+            HTML <style> tag with CSS
+        """
+        css = self.render(pretty=pretty)
+        if pretty:
+            return f"<style>\n{css}\n</style>"
+        else:
+            return f"<style>{css}</style>"
+
+    def count_classes(self) -> int:
+        """
+        Get the number of registered classes.
+
+        Returns:
+            Number of classes
+        """
+        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 list(self._classes.keys())
+
+    def to_dict(self) -> Dict:
+        """
+        Serialize stylesheet to dictionary.
+
+        Returns:
+            Dictionary representation
+        """
+        return {
+            "classes": {name: style.to_dict() for name, style in self._classes.items()},
+            "breakpoints": self._breakpoint_values.copy(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict, theme: Optional["Theme"] = None) -> "StyleSheet":
+        """
+        Deserialize stylesheet from dictionary.
+
+        Args:
+            data: Dictionary representation
+            theme: Optional theme to include
+
+        Returns:
+            New StyleSheet object
+        """
+        stylesheet = cls(theme=theme)
+
+        # Restore breakpoints
+        if "breakpoints" in data:
+            stylesheet._breakpoint_values = data["breakpoints"].copy()
+
+        # Restore classes
+        if "classes" in data:
+            for name, style_data in data["classes"].items():
+                style = CSSStyle.from_dict(style_data)
+                stylesheet._classes[name] = style
+
+        return stylesheet
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"StyleSheet(classes={self.count_classes()})"
diff --git a/src/ydnatl/styles/theme.py b/src/ydnatl/styles/theme.py
new file mode 100644
index 0000000..00f03c3
--- /dev/null
+++ b/src/ydnatl/styles/theme.py
@@ -0,0 +1,428 @@
+"""Theme class for YDNATL styling system."""
+
+from typing import Dict, Optional, Any
+
+from .style import CSSStyle
+
+
+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()
+    """
+
+    def __init__(
+        self,
+        name: str = "Default",
+        colors: Optional[Dict[str, str]] = None,
+        typography: Optional[Dict[str, Any]] = None,
+        spacing: Optional[Dict[str, str]] = None,
+        components: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize a Theme.
+
+        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
+        """
+        self.name = name
+        self.colors = colors or {}
+        self.typography = typography or {}
+        self.spacing = spacing or {}
+        self.components = components or {}
+
+    def get_css_variables(self) -> Dict[str, str]:
+        """
+        Generate CSS variables from theme properties.
+
+        Returns:
+            Dictionary of CSS variable names and values
+        """
+        variables = {}
+
+        # Color variables
+        for key, value in self.colors.items():
+            variables[f"--color-{key}"] = value
+
+        # Spacing variables
+        for key, value in self.spacing.items():
+            variables[f"--spacing-{key}"] = value
+
+        # Typography variables
+        if isinstance(self.typography, dict):
+            for key, value in self.typography.items():
+                if isinstance(value, str):
+                    variables[f"--font-{key}"] = value
+                elif isinstance(value, dict):
+                    # Handle nested typography settings
+                    for sub_key, sub_value in value.items():
+                        variables[f"--font-{key}-{sub_key}"] = str(sub_value)
+
+        return variables
+
+    def get_component_style(
+        self, component: str, variant: str = "default"
+    ) -> Optional[CSSStyle]:
+        """
+        Get a component style from the theme.
+
+        Args:
+            component: Component name (e.g., "button", "card")
+            variant: Variant name (e.g., "primary", "secondary")
+
+        Returns:
+            CSSStyle object or None if not found
+        """
+        if component not in self.components:
+            return None
+
+        comp_styles = self.components[component]
+
+        if isinstance(comp_styles, CSSStyle):
+            return comp_styles
+        elif isinstance(comp_styles, dict) and variant in comp_styles:
+            return comp_styles[variant]
+
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize theme to dictionary.
+
+        Returns:
+            Dictionary representation
+        """
+        return {
+            "name": self.name,
+            "colors": self.colors.copy(),
+            "typography": self.typography.copy(),
+            "spacing": self.spacing.copy(),
+            "components": {
+                name: (
+                    style.to_dict()
+                    if isinstance(style, CSSStyle)
+                    else {
+                        k: v.to_dict() if isinstance(v, CSSStyle) else v
+                        for k, v in style.items()
+                    }
+                )
+                for name, style in self.components.items()
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Theme":
+        """
+        Deserialize theme from dictionary.
+
+        Args:
+            data: Dictionary representation
+
+        Returns:
+            New Theme object
+        """
+        # Reconstruct components
+        components = {}
+        if "components" in data:
+            for name, comp_data in data["components"].items():
+                if isinstance(comp_data, dict):
+                    # Check if it's a style dict or variants dict
+                    if "styles" in comp_data:
+                        components[name] = CSSStyle.from_dict(comp_data)
+                    else:
+                        # It's variants
+                        components[name] = {
+                            k: CSSStyle.from_dict(v) if isinstance(v, dict) else v
+                            for k, v in comp_data.items()
+                        }
+
+        return cls(
+            name=data.get("name", "Default"),
+            colors=data.get("colors", {}),
+            typography=data.get("typography", {}),
+            spacing=data.get("spacing", {}),
+            components=components,
+        )
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"Theme(name='{self.name}')"
+
+    # Preset themes
+
+    @classmethod
+    def modern(cls) -> "Theme":
+        """
+        Modern theme with clean, contemporary design.
+
+        Returns:
+            Modern Theme object
+        """
+        return cls(
+            name="Modern",
+            colors={
+                "primary": "#3b82f6",
+                "primary-dark": "#2563eb",
+                "secondary": "#8b5cf6",
+                "secondary-dark": "#7c3aed",
+                "neutral": "#6b7280",
+                "success": "#10b981",
+                "danger": "#ef4444",
+                "warning": "#f59e0b",
+                "info": "#3b82f6",
+                "light": "#f3f4f6",
+                "dark": "#1f2937",
+                "white": "#ffffff",
+                "black": "#000000",
+            },
+            typography={
+                "body": "Inter, system-ui, -apple-system, sans-serif",
+                "heading": "Inter, system-ui, -apple-system, sans-serif",
+                "mono": "Consolas, Monaco, 'Courier New', monospace",
+                "sizes": {
+                    "xs": "12px",
+                    "sm": "14px",
+                    "base": "16px",
+                    "lg": "18px",
+                    "xl": "20px",
+                    "2xl": "24px",
+                    "3xl": "30px",
+                    "4xl": "36px",
+                },
+            },
+            spacing={
+                "xs": "4px",
+                "sm": "8px",
+                "md": "16px",
+                "lg": "24px",
+                "xl": "32px",
+                "2xl": "48px",
+                "3xl": "64px",
+            },
+            components={
+                "button": {
+                    "primary": CSSStyle(
+                        background_color="var(--color-primary)",
+                        color="var(--color-white)",
+                        padding="12px 24px",
+                        border_radius="6px",
+                        border="none",
+                        font_weight="600",
+                        cursor="pointer",
+                        transition="background-color 0.2s ease",
+                        _hover=CSSStyle(background_color="var(--color-primary-dark)"),
+                    ),
+                    "secondary": CSSStyle(
+                        background_color="var(--color-secondary)",
+                        color="var(--color-white)",
+                        padding="12px 24px",
+                        border_radius="6px",
+                        border="none",
+                        font_weight="600",
+                        cursor="pointer",
+                        transition="background-color 0.2s ease",
+                        _hover=CSSStyle(background_color="var(--color-secondary-dark)"),
+                    ),
+                },
+                "card": CSSStyle(
+                    background_color="var(--color-white)",
+                    padding="var(--spacing-lg)",
+                    border_radius="8px",
+                    box_shadow="0 1px 3px rgba(0, 0, 0, 0.1)",
+                ),
+            },
+        )
+
+    @classmethod
+    def classic(cls) -> "Theme":
+        """
+        Classic theme with traditional, timeless design.
+
+        Returns:
+            Classic Theme object
+        """
+        return cls(
+            name="Classic",
+            colors={
+                "primary": "#0066cc",
+                "primary-dark": "#004c99",
+                "secondary": "#6c757d",
+                "secondary-dark": "#5a6268",
+                "neutral": "#6c757d",
+                "success": "#28a745",
+                "danger": "#dc3545",
+                "warning": "#ffc107",
+                "info": "#17a2b8",
+                "light": "#f8f9fa",
+                "dark": "#343a40",
+                "white": "#ffffff",
+                "black": "#000000",
+            },
+            typography={
+                "body": "Georgia, 'Times New Roman', Times, serif",
+                "heading": "Georgia, 'Times New Roman', Times, serif",
+                "mono": "Courier New, Courier, monospace",
+                "sizes": {
+                    "xs": "12px",
+                    "sm": "14px",
+                    "base": "16px",
+                    "lg": "18px",
+                    "xl": "21px",
+                    "2xl": "24px",
+                    "3xl": "32px",
+                    "4xl": "40px",
+                },
+            },
+            spacing={
+                "xs": "4px",
+                "sm": "8px",
+                "md": "16px",
+                "lg": "24px",
+                "xl": "32px",
+                "2xl": "48px",
+                "3xl": "64px",
+            },
+            components={
+                "button": {
+                    "primary": CSSStyle(
+                        background_color="var(--color-primary)",
+                        color="var(--color-white)",
+                        padding="10px 20px",
+                        border_radius="4px",
+                        border="none",
+                        font_weight="400",
+                        cursor="pointer",
+                        transition="background-color 0.3s ease",
+                        _hover=CSSStyle(background_color="var(--color-primary-dark)"),
+                    ),
+                    "secondary": CSSStyle(
+                        background_color="var(--color-white)",
+                        color="var(--color-primary)",
+                        padding="10px 20px",
+                        border_radius="4px",
+                        border="2px solid var(--color-primary)",
+                        font_weight="400",
+                        cursor="pointer",
+                        transition="all 0.3s ease",
+                        _hover=CSSStyle(
+                            background_color="var(--color-primary)",
+                            color="var(--color-white)",
+                        ),
+                    ),
+                },
+                "card": CSSStyle(
+                    background_color="var(--color-white)",
+                    padding="var(--spacing-lg)",
+                    border_radius="4px",
+                    border="1px solid var(--color-light)",
+                    box_shadow="0 2px 4px rgba(0, 0, 0, 0.05)",
+                ),
+            },
+        )
+
+    @classmethod
+    def minimal(cls) -> "Theme":
+        """
+        Minimal theme with clean, stripped-down design.
+
+        Returns:
+            Minimal Theme object
+        """
+        return cls(
+            name="Minimal",
+            colors={
+                "primary": "#000000",
+                "primary-dark": "#333333",
+                "secondary": "#666666",
+                "secondary-dark": "#444444",
+                "neutral": "#999999",
+                "success": "#00cc00",
+                "danger": "#cc0000",
+                "warning": "#cc9900",
+                "info": "#0099cc",
+                "light": "#f5f5f5",
+                "dark": "#1a1a1a",
+                "white": "#ffffff",
+                "black": "#000000",
+            },
+            typography={
+                "body": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
+                "heading": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
+                "mono": "'SF Mono', Monaco, 'Cascadia Code', monospace",
+                "sizes": {
+                    "xs": "12px",
+                    "sm": "14px",
+                    "base": "16px",
+                    "lg": "18px",
+                    "xl": "20px",
+                    "2xl": "24px",
+                    "3xl": "32px",
+                    "4xl": "40px",
+                },
+            },
+            spacing={
+                "xs": "4px",
+                "sm": "8px",
+                "md": "16px",
+                "lg": "24px",
+                "xl": "32px",
+                "2xl": "48px",
+                "3xl": "64px",
+            },
+            components={
+                "button": {
+                    "primary": CSSStyle(
+                        background_color="var(--color-primary)",
+                        color="var(--color-white)",
+                        padding="8px 16px",
+                        border_radius="0px",
+                        border="none",
+                        font_weight="500",
+                        cursor="pointer",
+                        transition="opacity 0.2s ease",
+                        _hover=CSSStyle(opacity="0.8"),
+                    ),
+                    "secondary": CSSStyle(
+                        background_color="var(--color-white)",
+                        color="var(--color-primary)",
+                        padding="8px 16px",
+                        border_radius="0px",
+                        border="1px solid var(--color-primary)",
+                        font_weight="500",
+                        cursor="pointer",
+                        transition="all 0.2s ease",
+                        _hover=CSSStyle(
+                            background_color="var(--color-primary)",
+                            color="var(--color-white)",
+                        ),
+                    ),
+                },
+                "card": CSSStyle(
+                    background_color="var(--color-white)",
+                    padding="var(--spacing-md)",
+                    border_radius="0px",
+                    border="1px solid var(--color-light)",
+                ),
+            },
+        )
diff --git a/tests/test_fragment.py b/tests/test_fragment.py
index 821032e..5f2cdb6 100644
--- a/tests/test_fragment.py
+++ b/tests/test_fragment.py
@@ -1,9 +1,9 @@
 import unittest
 
-from ydnatl.core.fragment import Fragment
 from ydnatl.core.element import HTMLElement
-from ydnatl.tags.text import H1, Paragraph, Span
+from ydnatl.core.fragment import Fragment
 from ydnatl.tags.layout import Div, Section
+from ydnatl.tags.text import H1, Paragraph, Span
 
 
 class TestFragment(unittest.TestCase):
diff --git a/tests/test_parser.py b/tests/test_parser.py
new file mode 100644
index 0000000..8eb211f
--- /dev/null
+++ b/tests/test_parser.py
@@ -0,0 +1,357 @@
+import unittest
+
+from ydnatl.core.element import HTMLElement
+from ydnatl.core.parser import from_html
+
+
+class TestHTMLParser(unittest.TestCase):
+
+    def test_parse_simple_element(self):
+        """Test parsing a simple single element."""
+        html = "<div>Hello World</div>"
+        element = from_html(html)
+
+        self.assertIsNotNone(element)
+        self.assertEqual(element.tag, "div")
+        self.assertEqual(element.text, "Hello World")
+        self.assertEqual(len(element.children), 0)
+
+    def test_parse_element_with_attributes(self):
+        """Test parsing element with attributes."""
+        html = '<div id="main" class="container" data-value="123">Content</div>'
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        self.assertEqual(element.get_attribute("id"), "main")
+        self.assertEqual(element.get_attribute("class_name"), "container")
+        self.assertEqual(
+            element.get_attribute("data-value"), "123"
+        )  # Stored with hyphen
+        self.assertEqual(element.text, "Content")
+
+    def test_parse_nested_elements(self):
+        """Test parsing nested HTML elements."""
+        html = """
+        <div class="outer">
+            <h1>Title</h1>
+            <p>Paragraph content</p>
+        </div>
+        """
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        self.assertEqual(element.get_attribute("class_name"), "outer")
+        self.assertEqual(len(element.children), 2)
+
+        # Check first child (h1)
+        h1 = element.children[0]
+        self.assertEqual(h1.tag, "h1")
+        self.assertEqual(h1.text, "Title")
+
+        # Check second child (p)
+        p = element.children[1]
+        self.assertEqual(p.tag, "p")
+        self.assertEqual(p.text, "Paragraph content")
+
+    def test_parse_deeply_nested_elements(self):
+        """Test parsing deeply nested structure."""
+        html = """
+        <div>
+            <section>
+                <article>
+                    <h1>Deep Title</h1>
+                    <p>Deep content</p>
+                </article>
+            </section>
+        </div>
+        """
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        section = element.children[0]
+        self.assertEqual(section.tag, "section")
+        article = section.children[0]
+        self.assertEqual(article.tag, "article")
+        self.assertEqual(len(article.children), 2)
+
+    def test_parse_self_closing_tags(self):
+        """Test parsing self-closing/void elements."""
+        html = '<div><br /><img src="test.jpg" alt="Test" /><hr /></div>'
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        self.assertEqual(len(element.children), 3)
+
+        # Check br
+        br = element.children[0]
+        self.assertEqual(br.tag, "br")
+        self.assertTrue(br.self_closing)
+
+        # Check img
+        img = element.children[1]
+        self.assertEqual(img.tag, "img")
+        self.assertTrue(img.self_closing)
+        self.assertEqual(img.get_attribute("src"), "test.jpg")
+        self.assertEqual(img.get_attribute("alt"), "Test")
+
+        # Check hr
+        hr = element.children[2]
+        self.assertEqual(hr.tag, "hr")
+        self.assertTrue(hr.self_closing)
+
+    def test_parse_mixed_content(self):
+        """Test parsing elements with mixed text and child elements."""
+        html = "<div>Before<span>Middle</span>After</div>"
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        # Text before span
+        self.assertIn("Before", element.text)
+        # Check span child
+        self.assertEqual(len(element.children), 1)
+        span = element.children[0]
+        self.assertEqual(span.tag, "span")
+        self.assertEqual(span.text, "Middle")
+
+    def test_parse_fragment_multiple_roots(self):
+        """Test parsing HTML fragment with multiple root elements."""
+        html = "<h1>Title</h1><p>Paragraph 1</p><p>Paragraph 2</p>"
+        elements = from_html(html, fragment=True)
+
+        self.assertEqual(len(elements), 3)
+
+        # Check elements
+        self.assertEqual(elements[0].tag, "h1")
+        self.assertEqual(elements[0].text, "Title")
+
+        self.assertEqual(elements[1].tag, "p")
+        self.assertEqual(elements[1].text, "Paragraph 1")
+
+        self.assertEqual(elements[2].tag, "p")
+        self.assertEqual(elements[2].text, "Paragraph 2")
+
+    def test_parse_empty_element(self):
+        """Test parsing empty element."""
+        html = "<div></div>"
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        self.assertEqual(element.text, "")
+        self.assertEqual(len(element.children), 0)
+
+    def test_parse_complex_structure(self):
+        """Test parsing complex HTML structure."""
+        html = """
+        <html>
+            <head>
+                <title>Test Page</title>
+                <meta charset="utf-8" />
+            </head>
+            <body>
+                <header>
+                    <h1>Main Title</h1>
+                    <nav>
+                        <a href="/">Home</a>
+                        <a href="/about">About</a>
+                    </nav>
+                </header>
+                <main>
+                    <article>
+                        <h2>Article Title</h2>
+                        <p>Article content.</p>
+                    </article>
+                </main>
+                <footer>
+                    <p>Copyright 2024</p>
+                </footer>
+            </body>
+        </html>
+        """
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "html")
+        self.assertEqual(len(element.children), 2)
+
+        # Check head
+        head = element.children[0]
+        self.assertEqual(head.tag, "head")
+
+        # Check body
+        body = element.children[1]
+        self.assertEqual(body.tag, "body")
+        self.assertEqual(len(body.children), 3)
+
+    def test_parse_special_characters(self):
+        """Test parsing HTML with special characters."""
+        html = "<div>Hello &amp; Goodbye</div>"
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        # HTML entities should be decoded by the parser
+        self.assertIn("&", element.text)
+
+    def test_parse_attributes_without_values(self):
+        """Test parsing boolean attributes."""
+        html = '<input type="checkbox" checked disabled />'
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "input")
+        self.assertEqual(element.get_attribute("type"), "checkbox")
+        self.assertTrue(element.has_attribute("checked"))
+        self.assertTrue(element.has_attribute("disabled"))
+
+    def test_parse_style_attribute(self):
+        """Test parsing inline style attribute."""
+        html = '<div style="color: red; font-size: 16px;">Styled</div>'
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "div")
+        self.assertEqual(element.get_attribute("style"), "color: red; font-size: 16px;")
+
+    def test_parse_data_attributes(self):
+        """Test parsing data-* attributes."""
+        html = '<div data-id="123" data-name="test" data-active="true">Content</div>'
+        element = from_html(html)
+
+        # Attributes are stored with hyphens (kebab-case)
+        self.assertEqual(element.get_attribute("data-id"), "123")
+        self.assertEqual(element.get_attribute("data-name"), "test")
+        self.assertEqual(element.get_attribute("data-active"), "true")
+
+    def test_parse_and_render_roundtrip(self):
+        """Test that parsing and rendering produces similar output."""
+        html = '<div class="container"><h1>Title</h1><p>Content</p></div>'
+        element = from_html(html)
+
+        rendered = element.render()
+
+        # Parse the rendered output
+        element2 = from_html(rendered)
+
+        # Should have same structure
+        self.assertEqual(element.tag, element2.tag)
+        self.assertEqual(
+            element.get_attribute("class_name"), element2.get_attribute("class_name")
+        )
+        self.assertEqual(len(element.children), len(element2.children))
+
+    def test_htmlelement_from_html_classmethod(self):
+        """Test using HTMLElement.from_html() class method."""
+        html = '<div id="test">Content</div>'
+        element = HTMLElement.from_html(html)
+
+        self.assertIsNotNone(element)
+        self.assertEqual(element.tag, "div")
+        self.assertEqual(element.get_attribute("id"), "test")
+        self.assertEqual(element.text, "Content")
+
+    def test_htmlelement_from_html_fragment(self):
+        """Test using HTMLElement.from_html() with fragment=True."""
+        html = "<h1>One</h1><h2>Two</h2>"
+        elements = HTMLElement.from_html(html, fragment=True)
+
+        self.assertEqual(len(elements), 2)
+        self.assertEqual(elements[0].tag, "h1")
+        self.assertEqual(elements[1].tag, "h2")
+
+    def test_parse_form_elements(self):
+        """Test parsing form elements."""
+        html = """
+        <form action="/submit" method="post">
+            <label for="name">Name:</label>
+            <input type="text" id="name" name="name" required />
+            <button type="submit">Submit</button>
+        </form>
+        """
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "form")
+        self.assertEqual(element.get_attribute("action"), "/submit")
+        self.assertEqual(element.get_attribute("method"), "post")
+        self.assertEqual(len(element.children), 3)
+
+    def test_parse_table_structure(self):
+        """Test parsing table elements."""
+        html = """
+        <table>
+            <thead>
+                <tr>
+                    <th>Header 1</th>
+                    <th>Header 2</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td>Cell 1</td>
+                    <td>Cell 2</td>
+                </tr>
+            </tbody>
+        </table>
+        """
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "table")
+        self.assertEqual(len(element.children), 2)
+
+        thead = element.children[0]
+        self.assertEqual(thead.tag, "thead")
+
+        tbody = element.children[1]
+        self.assertEqual(tbody.tag, "tbody")
+
+    def test_parse_list_elements(self):
+        """Test parsing list elements."""
+        html = """
+        <ul class="list">
+            <li>Item 1</li>
+            <li>Item 2</li>
+            <li>Item 3</li>
+        </ul>
+        """
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "ul")
+        self.assertEqual(element.get_attribute("class_name"), "list")
+        self.assertEqual(len(element.children), 3)
+
+        for i, child in enumerate(element.children, 1):
+            self.assertEqual(child.tag, "li")
+            self.assertEqual(child.text, f"Item {i}")
+
+    def test_parse_whitespace_handling(self):
+        """Test that whitespace-only text nodes are ignored."""
+        html = """
+        <div>
+            <p>Paragraph 1</p>
+            <p>Paragraph 2</p>
+        </div>
+        """
+        element = from_html(html)
+
+        # Should not have whitespace text nodes
+        self.assertEqual(len(element.children), 2)
+        self.assertEqual(element.children[0].tag, "p")
+        self.assertEqual(element.children[1].tag, "p")
+
+    def test_parse_script_and_style_tags(self):
+        """Test parsing script and style tags."""
+        html = """
+        <head>
+            <style>body { margin: 0; }</style>
+            <script>console.log("test");</script>
+        </head>
+        """
+        element = from_html(html)
+
+        self.assertEqual(element.tag, "head")
+        self.assertEqual(len(element.children), 2)
+
+        style = element.children[0]
+        self.assertEqual(style.tag, "style")
+
+        script = element.children[1]
+        self.assertEqual(script.tag, "script")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_styles.py b/tests/test_styles.py
new file mode 100644
index 0000000..ecc1094
--- /dev/null
+++ b/tests/test_styles.py
@@ -0,0 +1,408 @@
+"""Tests for YDNATL styling system."""
+
+from ydnatl.styles import CSSStyle, StyleSheet, Theme
+
+
+class TestCSSStyle:
+    """Tests for CSSStyle class."""
+
+    def test_basic_style_creation(self):
+        """Test creating a basic CSS style."""
+        style = CSSStyle(background_color="#007bff", color="white", padding="10px 20px")
+
+        assert style._styles["background-color"] == "#007bff"
+        assert style._styles["color"] == "white"
+        assert style._styles["padding"] == "10px 20px"
+
+    def test_snake_case_to_kebab_case(self):
+        """Test conversion of snake_case to kebab-case."""
+        style = CSSStyle(background_color="blue", font_size="14px", border_radius="5px")
+
+        assert "background-color" in style._styles
+        assert "font-size" in style._styles
+        assert "border-radius" in style._styles
+
+    def test_pseudo_selectors(self):
+        """Test pseudo-selector support."""
+        style = CSSStyle(
+            background_color="#007bff",
+            _hover=CSSStyle(background_color="#0056b3"),
+            _active=CSSStyle(transform="scale(0.98)"),
+        )
+
+        assert "hover" in style._pseudo
+        assert style._pseudo["hover"]._styles["background-color"] == "#0056b3"
+        assert "active" in style._pseudo
+        assert style._pseudo["active"]._styles["transform"] == "scale(0.98)"
+
+    def test_breakpoints(self):
+        """Test responsive breakpoint support."""
+        style = CSSStyle(
+            padding="10px", _sm=CSSStyle(padding="15px"), _md=CSSStyle(padding="20px")
+        )
+
+        assert "sm" in style._breakpoints
+        assert style._breakpoints["sm"]._styles["padding"] == "15px"
+        assert "md" in style._breakpoints
+        assert style._breakpoints["md"]._styles["padding"] == "20px"
+
+    def test_to_inline(self):
+        """Test inline style generation."""
+        style = CSSStyle(background_color="blue", color="white", padding="10px")
+
+        inline = style.to_inline()
+        assert "background-color: blue" in inline
+        assert "color: white" in inline
+        assert "padding: 10px" in inline
+
+    def test_merge(self):
+        """Test merging two styles."""
+        style1 = CSSStyle(background_color="blue", color="white")
+        style2 = CSSStyle(color="black", padding="10px")
+
+        merged = style1.merge(style2)
+        assert merged._styles["background-color"] == "blue"
+        assert merged._styles["color"] == "black"  # Overridden
+        assert merged._styles["padding"] == "10px"
+
+    def test_has_pseudo_or_breakpoints(self):
+        """Test detection of pseudo-selectors and breakpoints."""
+        style1 = CSSStyle(background_color="blue")
+        assert not style1.has_pseudo_or_breakpoints()
+
+        style2 = CSSStyle(
+            background_color="blue", _hover=CSSStyle(background_color="red")
+        )
+        assert style2.has_pseudo_or_breakpoints()
+
+        style3 = CSSStyle(padding="10px", _md=CSSStyle(padding="20px"))
+        assert style3.has_pseudo_or_breakpoints()
+
+    def test_is_complex(self):
+        """Test complexity detection."""
+        simple = CSSStyle(color="blue")
+        assert not simple.is_complex(threshold=3)
+
+        complex_style = CSSStyle(
+            color="blue", background_color="white", padding="10px", margin="5px"
+        )
+        assert complex_style.is_complex(threshold=3)
+
+    def test_to_dict_and_from_dict(self):
+        """Test serialization and deserialization."""
+        original = CSSStyle(
+            background_color="blue",
+            color="white",
+            _hover=CSSStyle(background_color="red"),
+        )
+
+        data = original.to_dict()
+        restored = CSSStyle.from_dict(data)
+
+        assert restored._styles == original._styles
+        assert "hover" in restored._pseudo
+        assert restored._pseudo["hover"]._styles["background-color"] == "red"
+
+    def test_equality(self):
+        """Test style equality comparison."""
+        style1 = CSSStyle(color="blue", padding="10px")
+        style2 = CSSStyle(color="blue", padding="10px")
+        style3 = CSSStyle(color="red", padding="10px")
+
+        assert style1 == style2
+        assert style1 != style3
+
+
+class TestStyleSheet:
+    """Tests for StyleSheet class."""
+
+    def test_register_style(self):
+        """Test registering a style."""
+        stylesheet = StyleSheet()
+        style = CSSStyle(background_color="blue", color="white")
+
+        class_name = stylesheet.register("btn-primary", style)
+
+        assert class_name == "btn-primary"
+        assert stylesheet.has_class("btn-primary")
+        assert stylesheet.get_style("btn-primary") == style
+
+    def test_auto_generate_class_name(self):
+        """Test auto-generation of class names."""
+        stylesheet = StyleSheet()
+        style = CSSStyle(color="blue")
+
+        class_name = stylesheet.register(style=style)
+
+        assert class_name.startswith("s-")
+        assert stylesheet.has_class(class_name)
+
+    def test_register_bem(self):
+        """Test BEM naming convention."""
+        stylesheet = StyleSheet()
+        style = CSSStyle(color="blue")
+
+        # Block only
+        block_class = stylesheet.register_bem("button", style=style)
+        assert block_class == "button"
+
+        # Block + Element
+        element_class = stylesheet.register_bem("button", element="icon", style=style)
+        assert element_class == "button__icon"
+
+        # Block + Modifier
+        modifier_class = stylesheet.register_bem(
+            "button", modifier="primary", style=style
+        )
+        assert modifier_class == "button--primary"
+
+        # Block + Element + Modifier
+        full_class = stylesheet.register_bem(
+            "button", element="icon", modifier="large", style=style
+        )
+        assert full_class == "button__icon--large"
+
+    def test_render_basic_styles(self):
+        """Test rendering basic CSS."""
+        stylesheet = StyleSheet()
+        stylesheet.register("test", CSSStyle(color="blue", padding="10px"))
+
+        css = stylesheet.render()
+
+        assert ".test {" in css
+        assert "color: blue;" in css
+        assert "padding: 10px;" in css
+
+    def test_render_with_pseudo_selectors(self):
+        """Test rendering with pseudo-selectors."""
+        stylesheet = StyleSheet()
+        stylesheet.register("btn", CSSStyle(color="blue", _hover=CSSStyle(color="red")))
+
+        css = stylesheet.render()
+
+        assert ".btn {" in css
+        assert ".btn:hover {" in css
+        assert "color: red;" in css
+
+    def test_render_with_breakpoints(self):
+        """Test rendering with responsive breakpoints."""
+        stylesheet = StyleSheet()
+        stylesheet.register(
+            "container", CSSStyle(padding="10px", _md=CSSStyle(padding="20px"))
+        )
+
+        css = stylesheet.render()
+
+        assert ".container {" in css
+        assert "padding: 10px;" in css
+        assert "@media (min-width: 768px)" in css
+        assert "padding: 20px;" in css
+
+    def test_render_with_theme(self):
+        """Test rendering with theme CSS variables."""
+        theme = Theme(colors={"primary": "#007bff"}, spacing={"md": "16px"})
+        stylesheet = StyleSheet(theme=theme)
+
+        css = stylesheet.render()
+
+        assert ":root {" in css
+        assert "--color-primary: #007bff;" in css
+        assert "--spacing-md: 16px;" in css
+
+    def test_to_style_tag(self):
+        """Test generating a complete style tag."""
+        stylesheet = StyleSheet()
+        stylesheet.register("test", CSSStyle(color="blue"))
+
+        tag = stylesheet.to_style_tag()
+
+        assert tag.startswith("<style>")
+        assert tag.endswith("</style>")
+        assert ".test {" in tag
+
+    def test_unregister(self):
+        """Test removing a registered class."""
+        stylesheet = StyleSheet()
+        stylesheet.register("test", CSSStyle(color="blue"))
+
+        assert stylesheet.has_class("test")
+        result = stylesheet.unregister("test")
+        assert result is True
+        assert not stylesheet.has_class("test")
+
+        # Try removing non-existent class
+        result = stylesheet.unregister("non-existent")
+        assert result is False
+
+    def test_clear(self):
+        """Test clearing all classes."""
+        stylesheet = StyleSheet()
+        stylesheet.register("test1", CSSStyle(color="blue"))
+        stylesheet.register("test2", CSSStyle(color="red"))
+
+        assert stylesheet.count_classes() == 2
+        stylesheet.clear()
+        assert stylesheet.count_classes() == 0
+
+    def test_get_all_class_names(self):
+        """Test getting all class names."""
+        stylesheet = StyleSheet()
+        stylesheet.register("test1", CSSStyle(color="blue"))
+        stylesheet.register("test2", CSSStyle(color="red"))
+
+        names = stylesheet.get_all_class_names()
+        assert "test1" in names
+        assert "test2" in names
+        assert len(names) == 2
+
+    def test_to_dict_and_from_dict(self):
+        """Test stylesheet serialization."""
+        original = StyleSheet()
+        original.register("btn", CSSStyle(color="blue", _hover=CSSStyle(color="red")))
+
+        data = original.to_dict()
+        restored = StyleSheet.from_dict(data)
+
+        assert restored.has_class("btn")
+        assert restored.get_style("btn")._styles["color"] == "blue"
+
+
+class TestTheme:
+    """Tests for Theme class."""
+
+    def test_create_custom_theme(self):
+        """Test creating a custom theme."""
+        theme = Theme(
+            name="Custom", colors={"primary": "#007bff"}, spacing={"md": "16px"}
+        )
+
+        assert theme.name == "Custom"
+        assert theme.colors["primary"] == "#007bff"
+        assert theme.spacing["md"] == "16px"
+
+    def test_get_css_variables(self):
+        """Test CSS variable generation."""
+        theme = Theme(
+            colors={"primary": "#007bff", "secondary": "#6c757d"},
+            spacing={"sm": "8px", "md": "16px"},
+        )
+
+        variables = theme.get_css_variables()
+
+        assert variables["--color-primary"] == "#007bff"
+        assert variables["--color-secondary"] == "#6c757d"
+        assert variables["--spacing-sm"] == "8px"
+        assert variables["--spacing-md"] == "16px"
+
+    def test_get_component_style(self):
+        """Test getting component styles."""
+        theme = Theme(
+            components={
+                "button": {
+                    "primary": CSSStyle(background_color="blue"),
+                    "secondary": CSSStyle(background_color="gray"),
+                }
+            }
+        )
+
+        primary = theme.get_component_style("button", "primary")
+        assert primary._styles["background-color"] == "blue"
+
+        secondary = theme.get_component_style("button", "secondary")
+        assert secondary._styles["background-color"] == "gray"
+
+    def test_modern_preset(self):
+        """Test modern preset theme."""
+        theme = Theme.modern()
+
+        assert theme.name == "Modern"
+        assert "primary" in theme.colors
+        assert "body" in theme.typography
+        assert "md" in theme.spacing
+        assert "button" in theme.components
+
+    def test_classic_preset(self):
+        """Test classic preset theme."""
+        theme = Theme.classic()
+
+        assert theme.name == "Classic"
+        assert "primary" in theme.colors
+        assert theme.typography["body"] == "Georgia, 'Times New Roman', Times, serif"
+
+    def test_minimal_preset(self):
+        """Test minimal preset theme."""
+        theme = Theme.minimal()
+
+        assert theme.name == "Minimal"
+        assert theme.colors["primary"] == "#000000"
+
+    def test_to_dict_and_from_dict(self):
+        """Test theme serialization."""
+        original = Theme(
+            name="Test",
+            colors={"primary": "#007bff"},
+            components={"button": CSSStyle(color="blue")},
+        )
+
+        data = original.to_dict()
+        restored = Theme.from_dict(data)
+
+        assert restored.name == "Test"
+        assert restored.colors["primary"] == "#007bff"
+        assert "button" in restored.components
+
+
+class TestIntegration:
+    """Integration tests for the styling system."""
+
+    def test_complete_workflow(self):
+        """Test complete styling workflow."""
+        # Create theme
+        theme = Theme.modern()
+
+        # Create stylesheet with theme
+        stylesheet = StyleSheet(theme=theme)
+
+        # Register component styles
+        btn_primary = stylesheet.register(
+            "btn-primary",
+            CSSStyle(
+                background_color="var(--color-primary)",
+                color="white",
+                padding="12px 24px",
+                border_radius="6px",
+                _hover=CSSStyle(background_color="var(--color-primary-dark)"),
+            ),
+        )
+
+        # Render CSS
+        css = stylesheet.render()
+
+        # Verify output
+        assert ":root {" in css
+        assert "--color-primary:" in css
+        assert ".btn-primary {" in css
+        assert ".btn-primary:hover {" in css
+
+    def test_bem_workflow(self):
+        """Test BEM naming workflow."""
+        stylesheet = StyleSheet()
+
+        # Register BEM classes
+        stylesheet.register_bem(
+            "card", style=CSSStyle(background="white", padding="20px")
+        )
+        stylesheet.register_bem(
+            "card", element="header", style=CSSStyle(font_weight="bold")
+        )
+        stylesheet.register_bem("card", element="body", style=CSSStyle(padding="10px"))
+        stylesheet.register_bem(
+            "card", modifier="featured", style=CSSStyle(border="2px solid blue")
+        )
+
+        css = stylesheet.render()
+
+        assert ".card {" in css
+        assert ".card__header {" in css
+        assert ".card__body {" in css
+        assert ".card--featured {" in css
diff --git a/tests/test_text.py b/tests/test_text.py
index 85458ce..02f775b 100644
--- a/tests/test_text.py
+++ b/tests/test_text.py
@@ -1,5 +1,6 @@
 import unittest
 
+from ydnatl.core.element import HTMLElement
 from ydnatl.tags.text import (
     H1,
     H2,
@@ -36,7 +37,6 @@
     Br,
     Wbr,
 )
-from ydnatl.core.element import HTMLElement
 
 
 class TestTextTags(unittest.TestCase):