スタイルとテーマ設定

複雑な技術図解において、描画呼び出しのたびに RGB タプルや線幅、フォントウェイトを手動で指定すると、視覚的な一貫性が損なわれ、保守しづらいコードになってしまいます。 Drawlib は drawlib.styles と drawlib.preset_styles による統一デザイントークンシステムによってこの課題を解決します。

1. セマンティックスタイルとバリアントの概要

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. styles.py による一元管理アーキテクチャ

Drawlib は、プロジェクトで有効なトークン（drawlib.styles）とイミュータブルなファクトリカタログ（drawlib.preset_styles および drawlib.preset_colors）を明確に分離しています。

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

[!IMPORTANT] drawlib.styles からは必ず PascalCase の Styles と Colors をインポートしてください。小文字の styles や colors 変数を使うと、drawlib.styles モジュール自体をシャドーイングしてしまうため避けてください。

styles.py によるプロジェクト全体のデフォルトカスタマイズ

drawlib init で生成されたすべてのプロジェクトには、ルートに styles.py ファイルが含まれています。drawlib build や drawlib show の実行時、Drawlib は styles.py を読み込み、その Styles オブジェクトと Colors オブジェクトを 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. 統合 Style トークンモデル

ShapeStyle、LineStyle、TextStyle、IconStyle、ImageStyle のようにスタイルクラスを細分化する代わりに、Drawlib はドメイン別の接頭辞付き属性と明示的な対象ドメイン指定（supports={"shape", "line", "text", "icon", "image"}）を備えた単一のイミュータブルな Style クラス（from drawlib.types import Style）を採用しています。

3.2. 非破壊なスタイル派生 (.patch())

Style インスタンスは凍結（frozen）された Pydantic モデルです（dataclasses.replace を使う frozen dataclass と同様の設計）。グローバルなプリセット状態を変更せずにカスタムスタイルを派生させるには、.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. バリアント命名規則マトリクス

すべてのセマンティックロール（Primary、Secondary、Accent、Warning、Danger、Success、Neutral、Muted、Light、Dark）および色相名（Blue、Green、Red、Orange、Amber、Purple、Teal、Pink、Gray1..Gray8）には、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. プリセットテーマカタログ (drawlib.preset_styles)

Drawlib は drawlib.preset_styles において、3 つのデザインファミリーにわたる 9 個のプリセットスタイルクラスを提供しています。

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()