Styles & Theming

In complex technical diagrams, manually configuring RGB tuples, stroke widths, and font weights on every drawing call leads to visual inconsistency and brittle code. Drawlib solves this with a unified design token system in drawlib.styles and drawlib.preset_styles.

1. Overview of Semantic Styles & Variants

from drawlib.canvas import save, setup
from drawlib.shapes import rectangle
from drawlib.styles import Styles

setup(width=128, height=52)

# Row 1: Core Semantic Card & Hero Roles
rectangle((24, 37), width=35, height=18, style=Styles.PrimaryFlat.patch(shape_r=2), text="PrimaryFlat\n(Hero Focal)", text_style=Styles.WhiteBold.patch(text_size=10.5))
rectangle((64, 37), width=35, height=18, style=Styles.Neutral.patch(shape_r=2), text="Neutral\n(50%+ Baseline)", text_style=Styles.DarkBold.patch(text_size=10.5))
rectangle((104, 37), width=35, height=18, style=Styles.SecondaryNeutral.patch(shape_r=2), text="SecondaryNeutral\n(Auxiliary Card)", text_style=Styles.DarkBold.patch(text_size=10.5))

# Row 2: Structural & Status Variants
rectangle((24, 15), width=35, height=18, style=Styles.SuccessNeutral.patch(shape_r=2), text="SuccessNeutral\n(Verified State)", text_style=Styles.DarkBold.patch(text_size=10.5))
rectangle((64, 15), width=35, height=18, style=Styles.DangerFlat.patch(shape_r=2), text="DangerFlat\n(Critical Alert)", text_style=Styles.WhiteBold.patch(text_size=10.5))
rectangle((104, 15), width=35, height=18, style=Styles.MutedDashed.patch(shape_r=2), text="MutedDashed\n(VPC / Boundary)", text_style=Styles.DarkBold.patch(text_size=10.5))

save()

2. Centralized styles.py Architecture

Drawlib separates active project tokens (drawlib.styles) from immutable factory catalogs (drawlib.preset_styles and drawlib.preset_colors):

# Recommended in all drawing scripts and markdown blocks:
from drawlib.styles import Colors, Styles

[!IMPORTANT] Always import PascalCase Styles and Colors from drawlib.styles. Never use lowercase styles or colors variables, which would shadow the drawlib.styles module.

Customizing Project-Wide Defaults in styles.py

Every project scaffolded with drawlib init includes a root styles.py file. When drawlib build or drawlib show runs, Drawlib loads styles.py and binds its Styles and Colors objects into drawlib.styles:

# styles.py
from drawlib.fonts import FontRoboto
from drawlib.preset_colors import GoogleColors
from drawlib.preset_styles import GoogleStyles

Colors = GoogleColors()
Styles = GoogleStyles().patch_font(
    regular=FontRoboto.ROBOTO_REGULAR,
    bold=FontRoboto.ROBOTO_BOLD,
    thin=FontRoboto.ROBOTO_THIN,
)

from drawlib.canvas import save, setup
from drawlib.lines import line
from drawlib.shapes import rectangle
from drawlib.styles import Styles

setup(width=132, height=44)

stages = [
    (18.5, Styles.Neutral, "Immutable Presets\npreset_colors\npreset_styles", Styles.DarkBold),
    (50.2, Styles.SecondaryNeutral, "Project styles.py\nGlobal Theme &\nFont Patching", Styles.DarkBold),
    (81.8, Styles.PrimaryFlat, "Runtime Singleton\ndrawlib.styles\nColors, Styles", Styles.WhiteBold),
    (113.5, Styles.PrimaryNeutral, "Drawing Scripts\n& Docs Blocks\nSingle Source", Styles.DarkBold),
]

for cx, st, label, txt_st in stages:
    rectangle(
        (cx, 22),
        width=27,
        height=28,
        style=st.patch(shape_r=2),
        text=label,
        text_style=txt_st.patch(text_size=10.0),
    )

for x1, x2 in [(32, 36.7), (63.7, 68.3), (95.3, 100)]:
    line((x1, 22), (x2, 22), arrow_head="->", style=Styles.DarkBold)

save()

3. The Unified Style Token Model

Rather than fragmenting styling across separate ShapeStyle, LineStyle, TextStyle, IconStyle, and ImageStyle classes, Drawlib uses a single immutable Style class (from drawlib.types import Style) with domain-prefixed attributes and explicit target support (supports={"shape", "line", "text", "icon", "image"}):

3.2. Non-Mutating Derivation (.patch())

Style instances are frozen Pydantic models (similar to frozen dataclasses with dataclasses.replace). To customize a preset token without mutating global state, call .patch():

from drawlib.canvas import save, setup
from drawlib.lines import line
from drawlib.shapes import rectangle
from drawlib.styles import Styles
from drawlib.text import text

setup(width=124, height=46)

rectangle((62, 23), width=116, height=38, style=Styles.Neutral.patch(shape_r=2))

# 1. Original preset remains completely unchanged
rectangle(
    (28, 23),
    width=36,
    height=22,
    style=Styles.Primary,
    text="Styles.Primary\n(Original Preset)",
    text_style=Styles.WhiteBold.patch(text_size=10.5),
)

# 2. Derive a custom card & connector style via .patch()
highlight_card = Styles.Primary.patch(
    shape_r=4,
    shape_line_width=2.5,
    shape_line_style="dashed",
    line_width=2.5,
    line_style="dashed",
)

line((46, 23), (76, 23), arrow_head="->", style=highlight_card)
text((61, 29), ".patch()", style=Styles.DarkBold.patch(text_size=10.5))

rectangle(
    (95, 23),
    width=38,
    height=22,
    style=highlight_card,
    text="highlight_card\n(shape_r=4, dashed)",
    text_style=Styles.WhiteBold.patch(text_size=10.5),
)

save()

4. Complete Variant Naming Matrix

Every semantic role (Primary, Secondary, Accent, Warning, Danger, Success, Neutral, Muted, Light, Dark) and named hue (Blue, Green, Red, Orange, Amber, Purple, Teal, Pink, Gray1..Gray8) provides orthogonal visual variants following the grammar Styles.<RoleOrColor><Variant><Weight>:

from drawlib.canvas import save, setup
from drawlib.shapes import rectangle
from drawlib.styles import Styles
from drawlib.text import text

setup(width=128, height=58)

# Row 1: Filled & Tinted Card Variants
row1 = [
    (18.5, Styles.Neutral, "Neutral", Styles.DarkBold),
    (48.8, Styles.PrimaryNeutral, "PrimaryNeutral", Styles.DarkBold),
    (79.2, Styles.PrimaryFlat, "PrimaryFlat", Styles.WhiteBold),
    (109.5, Styles.PrimaryBold, "PrimaryBold", Styles.WhiteBold),
]
for x, st, label, txt_st in row1:
    rectangle((x, 42), width=27, height=18, style=st.patch(shape_r=2), text=label, text_style=txt_st.patch(text_size=10.0))

# Row 2: Wireframe / Stroke Variants (Outline/Solid, Dashed, Dotted)
row2 = [
    (18.5, Styles.PrimarySolid, "PrimarySolid"),
    (48.8, Styles.PrimarySolidBold, "SolidBold"),
    (79.2, Styles.MutedDashed, "MutedDashed"),
    (109.5, Styles.PrimaryDottedBold, "DottedBold"),
]
for x, st, label in row2:
    rectangle((x, 16), width=27, height=18, style=st.patch(shape_r=2))
    text((x, 16), label, style=Styles.DarkBold.patch(text_size=10.0))

save()

5. Preset Theme Catalogs (drawlib.preset_styles)

Drawlib ships with 9 preset style classes across three design families in drawlib.preset_styles:

from drawlib.canvas import save, setup
from drawlib.preset_styles import DefaultStyles, GoogleStyles, MonochromeStyles
from drawlib.shapes import rectangle
from drawlib.styles import Styles
from drawlib.text import text

setup(width=128, height=60)

themes = [
    (23, "DefaultStyles", DefaultStyles()),
    (64, "GoogleStyles", GoogleStyles()),
    (105, "Monochrome", MonochromeStyles()),
]

for cx, title, theme in themes:
    # Boundary container
    rectangle((cx, 30), width=37, height=48, style=theme.MutedDashed.patch(shape_r=2))
    text((cx, 48), title, style=Styles.DarkBold.patch(text_size=11.0))

    # Hero node (PrimaryFlat)
    rectangle((cx, 34), width=30, height=12, style=theme.PrimaryFlat.patch(shape_r=1.5), text="Hero Node", text_style=theme.WhiteBold.patch(text_size=10.5))

    # Supporting neutral card (SecondaryNeutral)
    rectangle((cx, 17), width=30, height=12, style=theme.SecondaryNeutral.patch(shape_r=1.5), text="Neutral Card", text_style=theme.DarkBold.patch(text_size=10.5))

save()