DEV Community: goodlords

I built a pure-frontend, all-in-one toolbox for the tasks I reach for every day

goodlords — Wed, 10 Jun 2026 09:02:26 +0000

After years of mobile development, one of the most annoying parts of my daily workflow is jumping between scattered tool websites.

Finding image assets means digging through folders layer by layer — SVG and Lottie need separate preview tools. Converting or compressing images means uploading to online converters. Debugging APIs means opening a JSON formatter. Inspecting an APK means yet another dedicated site. By the end of the day I have a dozen tabs open, constantly context-switching. Worse, many online tools require file uploads — internal project assets and unreleased builds always feel risky.

When things slowed down recently, I built a pure-frontend, all-in-one toolbox for the tasks I reach for every day. I call it AppForge. Core features run locally in the browser — files never leave your machine.

Resource Preview: find one icon in 2,870 files

This was the first module I built — and the one I use most — because it hits a daily pain point for our 40-person app team.

One project scan surfaces 2,870 resource files. Search close and you get 80+ near-identical close icons: inconsistent names, scattered paths, zero discipline. Can I push the whole team to clean this up overnight? Honestly, no.

But one missing asset blocks your whole flow. My take is simple: if I can't fix the mess, I can at least find what I need in seconds.

Select a local project folder — AppForge scans everything and recognizes SVG, WebP, PNG, GIF, Lottie, Vector, Iconfont, and more. The screenshot shows it in action: search close, filter Vector, 81 matches with instant preview and full paths. No Finder spelunking, no guessing the rest of the filename.

Results cache locally — reopen and you're ready. Onboarding legacy projects, auditing duplicate assets, or chasing "that little X close icon" — what used to take minutes now takes seconds.

File Conversion: image processing in one place

After finding assets comes format work: SVG → PNG for multi-platform, PNG → WebP for smaller bundles, HEIC → common formats, occasional background removal for marketing assets.

Instead of design software or multiple upload sites, the convert module handles format conversion, smart compression, and background removal — all locally. Drop files in, download results.

APK Inspector: unpack locally

Android devs regularly need to inspect APKs: competitor package names and versions, signatures and permissions, icons and resources.

Drag an APK into AppForge to view package info, Manifest, permissions, components, and export internal assets. Need decompilation? One click to JADX.

Image OCR: copy text from screenshots

Stack traces, design copy, code snippets in docs — often trapped in screenshots. The OCR module runs locally, supports Chinese and English, batch processing, one-click copy. Files stay on your machine.

Mini Tools: no more bookmark clutter

JSON formatting, Base64 / URL / Unicode encode-decode, regex testing, timestamp conversion — small but essential. Built-in presets for email, phone, ID, IP, and more.

AI-Curated Tech Articles: skip the noise

Another big pain point. As a mobile developer I skim tons of tech content daily — most of it is fluff, reposts, or clickbait.

The AI-curated articles section pulls candidates from DEV and Hacker News, scores each post with an LLM, and keeps only high-quality picks. Updated daily with cumulative history — past picks aren't wiped each run. Browse by category in Chinese or English — like having someone pre-filter for you.

Open APIs: quick reference for demos

Building a small demo often means hunting for free APIs, testing endpoints, bookmarking docs. I curated common APIs by category with sample calls — look up when you need them.

Why I built it this way

Simple goal: make my own workflow smoother.

Local-first: sensitive project assets and builds stay in the browser
Zero friction: no signup, no desktop install — just open and use
Real scenarios: every feature comes from actual daily pain points

Built with React 19 + Vite 8 + Tailwind CSS 4, deployed on Cloudflare Pages, with lazy loading, caching, and bilingual UI.

Started as a personal toolbox — after using it for a while I polished it for others. If you're a mobile developer tired of scattered tools, give it a try.

What's missing from your dev workstation? Share the tools and workflow tricks you can't live without in the comments — let's swap notes and level up together.

👉 Try it now: https://appforge-7tw.pages.dev

AppForge — AI-curated reads and dev tools at your fingertips, all-in-one.

Modern Android Architecture (Part 4): Design Patterns — The Glue of Lego Architecture

goodlords — Mon, 01 Jun 2026 02:06:48 +0000

Series Navigation: Article 1: A Decade of Android Architecture Evolution | Article 2: The Lego Architecture: Divide and Conquer, Taken to the Extreme | Article 3: Refactoring a Product Detail Page with Lego Architecture

Project Repository: https://github.com/zealot2002/androidArch

Foreword: Bricks Are Ready, How to Assemble Them Stably?

In the first three articles, we followed a clear path:

Article 1 pointed out: Architecture is just "technique" — it can manage layering, but not splitting granularity.
Article 2 proposed Lego Architecture: Split infinitely to minimum particles, making reuse visible.
Article 3 proved with practical product detail page: Bricks like Mapper, Assembler, ListItem can indeed split a 3000-line disaster into 15 independent components.

But there's a question hinted at the end of Article 3 — Splitting is only the first step; assembly determines whether this system can run long-term.

Two pages both require "login before operation" — do you plan to copy-paste two sets of if (isLogin) checks? Three types of posters (product, social, store) share the same "render → screenshot → preview → share" workflow, but with completely different UI layouts — do you plan to write three when branches in Activity, each hundreds of lines long?

This is where design patterns come in. They are not another "silver bullet architecture," but the glue between Lego bricks — using minimal, proven connection methods to stably assemble already-split particles together.

The 23 GoF patterns and more evolving patterns each solve different "assembly" problems: Factory is responsible for creating the right bricks, Strategy for switching replaceable behaviors, Adapter for connecting incompatible interfaces, Observer for responding to state changes, Template Method for solidifying invariant processes... Due to space constraints, this article won't cover all of them, but will select two representative cases from the demo project — Observer and Template Method — to illustrate how design patterns generally work in Lego Architecture.

Left: Product detail page from Article 3 — favorite, add to cart, and buy now gated by LoginRouter; Right: Three poster share pages (product / social / store) — sharing the BillActivity screenshot flow, each rendered by a different BaseBillRender subclass.

I. Observer Pattern: LoginRouter — The "Broadcast Station" for Login State

1.1 Pain Point: Login Interception Scattered Everywhere

In e-commerce apps, many operations depend on login state: favorite products, add to cart, buy now, post comments...

The crudest approach is to repeat this check in every click event:

if (UserManager.isLogin()) {
    doSomething()
} else {
    startActivity(Intent(this, LoginActivity::class.java))
}

The problems are:

Repetition: Ten buttons, ten copies of the same check logic.
Broken flow: After successful login, the original operation is often "lost" — the user has to click the button again.
Coupling: Some projects even write post-login navigation directly into LoginActivity, coupling the login module with other modules.

Lego Architecture requires: Extract "execute after login" as an independent, reusable brick.

1.2 Solution: Observer Pattern

LoginRouter consists of two observable sources (LifecycleOwner, LoginStateLiveData) and a pendingBlock:

LoginStateLiveData — Subscribe to login state. Publish true after successful login to trigger pending callbacks.
LifecycleOwner — Subscribe to page lifecycle. Clear pending when page is destroyed to avoid leaks; also clear on ON_RESUME — when user presses back from login page without logging in, pending operations should be abandoned.
pendingBlock — Store the "execute after login" operation. Suspended when not logged in, automatically invoke() after successful login.

Core code:

class LoginRouter(private var context: Context) {
    private var pendingBlock: (() -> Unit)? = null

    init {
        if (context is LifecycleOwner) {
            // Observer: Login success → execute pending operation
            LoginStateLiveData.observe(context as LifecycleOwner) {
                if (it) {
                    pendingBlock?.invoke()
                    pendingBlock = null
                }
            }
            // ON_RESUME: User returns from login page but not logged in (e.g., pressed back), abandon pending
            // ON_DESTROY: Page destroyed, clean up pending
            (context as LifecycleOwner).lifecycle.addObserver(
                LifecycleEventObserver { _, event ->
                    when (event) {
                        Lifecycle.Event.ON_RESUME,
                        Lifecycle.Event.ON_DESTROY -> pendingBlock = null
                        else -> {}
                    }
                }
            )
        }
    }

    fun runBlock(block: () -> Unit) {
        if (context is LifecycleOwner) {
            if (LoginStateLiveData.value == true) {
                block.invoke()
            } else {
                pendingBlock = block
                AppRouter.openLogin(context)
            }
        } else {
            block.invoke()
        }
    }
}

After successful login, the login page only needs to update the global state:

// LoginActivity
LoginStateLiveData.value = true
finish()

This is the complete Observer Pattern loop:

LoginActivity login successful
       │
       ▼
LoginStateLiveData.value = true   ← Subject publishes state
       │
       ▼
LoginRouter receives notification ← Observer
       │
       ▼
pendingBlock?.invoke()            ← Automatically execute suspended operation

1.3 Usage in Product Detail Page

In the refactored GoodsDetailActivity from Article 3, favorite, add to cart, and buy now are all handled with one line through LoginRouter:

private val loginRouter: LoginRouter by lazy { LoginRouter(this) }

// Favorite
loginRouter.runBlock {
    // Note: this is not a page navigation — it triggers a state update after login
    favViewModel.setFavorite(currentSpuId, targetFavorite)
}

// Add to cart
loginRouter.runBlock {
    ToastUtils.show(this, getString(R.string.goods_action_add_cart_hint))
}

// Buy now → Navigate to confirm order page after login
loginRouter.runBlock {
    AppRouter.openConfirmOrder(this)
}

The difference between LoginRouter and a route interceptor: interceptors usually only handle unified page navigation, while runBlock can queue any operation as pending — favorite, API request, show Toast, not limited to opening new pages. Subsequent actions are still declared locally in the page, and LoginActivity no longer needs to act as a transit hub. Module boundaries are clear and decoupled.

1.4 Origin and Boundaries

LoginRouter wasn't designed upfront; it emerged from project pain points.

After connecting favorite, add to cart, and buy now to the detail page, the same logic repeatedly appeared across multiple buttons: check login, navigate to login page, continue original operation after success. Interceptors could only intercept navigation uniformly, not handle "continue favorite after login"; writing destinations into LoginActivity would couple the login module with business logic. After several rounds of copy-paste, the pain point became clear — missing a common brick that can queue any follow-up action as pending.

Extract, observe, abstract: LoginRouter combines login guard and pending continuation into one brick, using LoginStateLiveData and LifecycleOwner to coordinate timing, elegantly solving this pain point.

Lego Architecture not only requires the ability to split, but also to see patterns in repetition and discover bricks in pain points — LoginRouter is one such refinement.

II. Template Method Pattern: BillActivity — Fixed Process, Variable Content

2.1 Pain Point: Three Poster Types, One Workflow

We added a poster sharing feature to the demo project — users can generate beautiful posters for products, social posts, or store pages, save to album, or share to WeChat.

The three poster types have completely different UI layouts, but the page-level workflow is identical:

Load data → Select Render → Bind view → Wait for render ready → Screenshot → Preview → Save/Share

If we write three sets of rendering logic in BillActivity using when (billCase), the Activity will quickly bloat; if we write a separate Activity for each poster type, the screenshot, preview, and save code will be duplicated three times.

Template Method Pattern solution: Solidify the "invariant process" in a template, leave "variable parts" for subclasses to implement.

2.2 Architecture Layers: Interface → Abstract Template → Concrete Implementation

Step 1: Define Brick Interface

interface BillRender {
    fun onBindView(data: Any, listener: Listener)
    fun getBillView(): View

    interface Listener {
        fun screenReady(bgBitmap: Bitmap? = null)
    }
}

BillRender is a standard interface — all poster Render bricks must follow these two methods.

Step 2: Abstract Template Class Solidifies Common Skeleton

abstract class BaseBillRender<T, B : ViewBinding>(private val context: Context) : BillRender {

    private lateinit var binding: B

    // Subclasses only implement this method — fill specific UI
    abstract fun onRenderView(data: T, binding: B, listener: BillRender.Listener)

    init {
        // Template method: Reflection automatically inflates corresponding ViewBinding
        val superclass = javaClass.genericSuperclass as ParameterizedType
        val bindingClass = superclass.actualTypeArguments[1] as Class<B>
        val inflate = bindingClass.getDeclaredMethod("inflate", LayoutInflater::class.java)
        binding = inflate.invoke(null, (context as Activity).layoutInflater) as B
    }

    override fun onBindView(data: Any, listener: BillRender.Listener) {
        onRenderView(data as T, binding, listener)  // Call subclass implementation
    }

    override fun getBillView(): View = binding.root
}

This is the core of Template Method Pattern:

BaseBillRender defines the algorithm skeleton (inflate Binding → call onRenderView → expose getBillView).
Subclasses only need to implement one hook: onRenderView, filling in their own UI logic.
Common ViewBinding initialization is done through generics + reflection, with zero boilerplate code for subclasses.

Step 3: Concrete Subclasses Only Care About Their UI, Need Only Implement One Method

Taking product poster as example:

class GoodsBillRender(context: Context) :
    BaseBillRender<GoodsBillData, LayoutBillGoodsBinding>(context) {

    override fun onRenderView(
        data: GoodsBillData,
        binding: LayoutBillGoodsBinding,
        listener: BillRender.Listener,
    ) {
        binding.tvTitle.text = data.title
        binding.tvPrice.text = data.price
        // ... Fill product-specific fields

        // Wait for layout drawing + network image loading to complete
        binding.ivCover.loadNetworkImage(data.imageUrl, onSuccess = { markReady() })
        binding.ivQrCode.loadNetworkImageCircle(data.miniProgramCodeUrl, onSuccess = { markReady() })
        // Call screenReady when all ready
    }
}

markReady() internally maintains a counter (product poster needs to wait for layout drawing + cover image + QR code = 3 items), and only triggers screenReady when the count is complete, ensuring complete content during screenshot.

SocialBillRender and ShopBillRender have the same structure, each binding different layouts and Data types. Adding a new poster type only requires adding a new Render subclass + one Layout XML, zero modifications to existing code.

Step 4: Factory Selects Concrete Brick

object BillRenderFactory {
    fun make(context: Context, case: Int): BillRender {
        return when (case) {
            RouterConstants.BILL_CASE_SOCIAL -> SocialBillRender(context)
            RouterConstants.BILL_CASE_SHOP -> ShopBillRender(context)
            else -> GoodsBillRender(context)
        }
    }
}

2.3 BillActivity: Orchestrating the Fixed Workflow

BillActivity itself contains no specific poster UI logic; it only orchestrates the template process:

class BillActivity : BaseActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        // ... Initialize views, share button

        // 1. Factory selects Render brick
        billRender = BillRenderFactory.make(this, billCase)
        binding.flBillContainer.addView(billRender.getBillView(), ...)

        // 2. Load data + bind view
        val billData = BillDataLoader.load(billCase, billId)
        billRender.onBindView(billData, object : BillRender.Listener {
            override fun screenReady(bgBitmap: Bitmap?) {
                captureBillSnapshot()  // 3. Render ready → screenshot
            }
        })
    }

    private fun captureBillSnapshot() {
        // 4. View → Bitmap → Preview display
        val bitmap = BillBitmapUtils.viewToBitmap(billRender.getBillView())
        binding.ivBill.setImageBitmap(bitmap)
        // 5. Show bottom save/share bar
    }
}

The responsibility boundaries are clear throughout the page:

Component	Responsibility	Pattern
`BillDataLoader`	Load Mock data by case	Simple Factory
`BillRenderFactory`	Select specific Render implementation	Simple Factory
`BaseBillRender`	Solidify inflate + bind skeleton	Template Method
`GoodsBillRender`, etc.	Fill specific UI + async ready detection	Template Method hooks
`BillActivity`	Orchestrate load → render → screenshot → preview → share	Process controller
`BillBitmapUtils` / `BillImageSaver`	Screenshot and save	Independent utility bricks

2.4 Echo with Article 2: When to Use Template Method?

In Article 2, we harshly criticized this kind of Base:

abstract class BaseActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initCallerData()   // Forced order
        initView()
        initPageData()
        initObservers()
    }
    abstract fun initView()
    abstract fun initPageData()
    // ...
}

Why is the template method in BaseBillRender acceptable, but not in BaseActivity?

	Bad BaseActivity Template	Good BaseBillRender Template
Is the process really consistent?	Different pages have very different initialization orders	All posters must inflate → bind → render → ready
Constrains order or structure?	Forces `initView` before `initData`	Only specifies "call `onRenderView` when binding data"
Subclass freedom	Kidnapped by four abstract methods	Only need to implement one `onRenderView`
Is it pluggable?	Must inherit Base to use	Just implement `BillRender` interface, no inheritance required

The judgment is simple: Only use template method when the algorithm skeleton is truly consistent across multiple subclasses; if you're just "incidentally" stuffing a bunch of optional initialization steps into Base, it's a shackle, not a template.

III. Gluing Approaches from Two Cases

The two cases above demonstrate two common "gluing" directions of design patterns in Lego Architecture — responding to changes and solidifying processes. Other patterns solve different dimensions of assembly problems like creation, replacement, adaptation, etc., with similar thinking.

Dimension	Observer (LoginRouter)	Template Method (BillRender)
Problem Solved	When A's state changes, B needs to respond automatically	Multiple subclasses share the same algorithm skeleton, only some steps differ
Connection Method	Subscription / Callback	Inherit abstract class + implement hook methods
Coupling Direction	Subject doesn't know who's observing (unidirectional)	Subclass depends on parent skeleton (unidirectional)
Lego Position	Cross-module event broadcasting brick	Common skeleton brick for similar Renders
Extension Method	Add new observers without modifying Subject	Add new subclasses without modifying template skeleton

Regardless of pattern, there's a common prerequisite: They are used to "glue" bricks after Lego splitting — not to replace splitting itself.

If you haven't split login logic into LoginRouter, Observer Pattern won't save you — you're just writing LiveData observations in three Activities. If you haven't split the three posters into independent Renders, Template Method won't save you either — BaseBillRender will be filled with if (case == SOCIAL) branches. Same for Factory, Strategy, and other patterns — Split first, then glue, order matters.

Beyond the two cases detailed in this article, the demo project has patterns working silently throughout — they're not the stars, but they're connectors between bricks:

Pattern	Location in Project	What It Glues
Observer	`LoginRouter`	Login state changes → cross-page pending follow-up operations
Template Method	`BaseBillRender`	Multiple posters share inflate → bind → render skeleton
Simple Factory	`BillRenderFactory`, `BillDataLoader`	Create corresponding Render / data by `billCase`
Strategy	`BillRender` and its implementations	Switch different poster rendering strategies under the same screenshot process
Adapter	`GoodsDetailAdapter`	14 types of `ListItem` → RecyclerView multi-type rendering

IV. Complete Lego Architecture System: Four Articles Connected

At this point, the four articles form a complete narrative:

Article 1: Problem Awareness
  └─ Architecture is just "technique", connection count determines complexity

Article 2: Splitting Methodology
  └─ Lego Architecture = Infinite splitting to minimum particles + Governance iteration

Article 3: Splitting Practice
  └─ Product Detail Page: ListItem + Mapper + Assembler + ViewModel

Article 4: The Glue
  └─ Design Patterns: On top of splitting, use appropriate patterns to stably assemble bricks (this article focuses on Observer and Template Method)

The complete Lego Architecture system can be summarized as:

One Axiom: Divide-and-conquer + Single Responsibility
Multiple Theorems: Governance thinking, tool iteration (Private→Shared→Remote), reuse discovery
One Practice: 15 independent components in product detail page
One Layer of Glue: Design patterns — this article focuses on Observer and Template Method; the project also uses Factory, Strategy, Adapter patterns for connection (see table above)

When you truly build applications with Lego thinking, you'll find:

Complexity doesn't come from the application itself, but from not splitting it into small enough bricks.
Design patterns aren't for showing off, but for selecting appropriate patterns by scenario after splitting, using minimal connections to stably assemble bricks.
Good code isn't written by learning one architecture, but by having divide-and-conquer awareness, governance discipline, pattern intuition, and the ability to spot reusable bricks.

Series Conclusion

Four articles, from "Architecture Evolution History" to "Lego Splitting Methodology", to "Product Detail Page Practice", and finally to "Design Pattern Glue" — we've tried to answer a consistent question:

How to truly improve Android code quality?

The answer isn't in the labels of MVVM or MVI, but in daily programming discipline: split until you can't split anymore, glue only when needed, govern for sustainable iteration.

May your codebase be like a box of Lego — each brick has clear responsibilities, stable interfaces, can be combined freely, and can still build new models after many years.

Related Reading:

Modern Android Architecture (Part 3): Refactoring a Product Detail Page with Lego Architecture: From 3000 Lines to 15 Standalone Components

goodlords — Mon, 01 Jun 2026 02:06:26 +0000

Series Navigation: Article 1: A Decade of Android Architecture Evolution | Article 2: The Lego Architecture: Divide and Conquer, Taken to the Extreme | Article 4: Design Patterns — The Glue of Lego Architecture

Project Repository: https://github.com/zealot2002/androidArch

Foreword: Product Detail Page — The "Touchstone" of Architecture

The product detail page is widely recognized as the "touchstone" of e-commerce app architecture. A standard detail page typically contains over 10 business sections: image carousel, price marketing, specification selection, user reviews, store information, product details, recommended products...

In traditional architecture, we've seen too many real and painful disasters:

Unclear overall control logic, no real "traffic hub": Page control logic is scattered across Activity, Fragment, Adapter, and even utility classes. You find code loading data in Activity, follow the call chain to ViewModel, then it might end up in an Adapter's internal callback. There's no centralized place to see "what this page does in what order."

Severe code redundancy: Redundant logic and slightly different code snippets are scattered everywhere. Either you don't know how to extract methods — always feeling the method name would be longer than the code itself — or you force an extraction that does multiple things (a method called updatePrice that also refreshes inventory, logs analytics, and shows a Toast).

Scattered glue code everywhere: Temporary flags, anonymous callbacks, nested conditionals... scattered throughout, reading like a book without table of contents or chapters.

Chaotic organization, vague responsibility boundaries: Although seemingly divided into classes or packages, data conversion, UI rendering, and business logic are often intertwined. Changing a price display logic might require jumping through five or six files along the call chain, always worrying about breaking unrelated logic.

Hard to find things: A price formatting method might be hidden in GoodsUtils, in a ViewModel's private method, or even hardcoded directly in an Adapter's onBindViewHolder. Newcomers spend most of their time "archaeological searching" rather than understanding business.

The essence of these problems isn't the lack of some "advanced architecture," but:

Not split into minimal particles — lacking the divide-and-conquer thinking advocated by Lego Architecture, code blocks are too large with too many responsibilities, making reuse and maintenance difficult.
Lack of governance thinking — no clear code organization standards or boundaries established, allowing redundant logic and glue code to proliferate until it spirals out of control.

As discussed in Article 2, the core of Lego Architecture is divide-and-conquer and single responsibility, along with practical methods like governance thinking, tool iteration, and reuse discovery. Today, we'll demonstrate with actual project code: how to apply Lego Architecture's "minimum granularity + dynamic assembly" philosophy to break down complex UI and business logic into independent, reusable, pluggable bricks using a product detail page as an example.

I. Core Design: Everything is a List Item — The Ultimate Practice of Minimum Granularity

Following Lego Architecture's principle of "infinite splitting to minimum particles," we need to break down the entire page into individual UI units. Following this idea, we choose to use a single RecyclerView to host all UI elements. While counterintuitive at first glance, this is a natural projection of divide-and-conquer thinking for list-based pages.

The benefits are:

Each UI unit corresponds to an independent list item type, with no nested dependencies between them
Scrolling performance is uniformly managed by RecyclerView, avoiding lag and memory issues from multi-layer nesting
Adding or removing sections doesn't require layout structure changes, just add/remove corresponding list items

1.1 Define a Unified Brick Interface

We use sealed class to define all list item types — our "brick inventory." Each list item brick has only one responsibility: describe the data needed for a UI section.

sealed class GoodsDetailListItem {
    // Product basic information sections
    data class PriceMarketing(val state: GoodsDetailProductSectionState) : GoodsDetailListItem() // Responsibility: Display price, promotion tags
    data class ProductTitle(val state: GoodsDetailProductSectionState) : GoodsDetailListItem()   // Responsibility: Display product title, subtitle
    data class ServiceSales(val state: GoodsDetailProductSectionState) : GoodsDetailListItem()   // Responsibility: Display service commitments, sales data
    data class AfterSales(val state: GoodsDetailProductSectionState) : GoodsDetailListItem()     // Responsibility: Display after-sales guarantee information

    // Specification and quantity sections
    data class SpecSelection(val state: GoodsDetailProductSectionState) : GoodsDetailListItem()   // Responsibility: Display specification selector (weight/flavor, etc.)
    data class PurchaseQuantity(val state: GoodsDetailProductSectionState) : GoodsDetailListItem() // Responsibility: Display quantity increment/decrement controls

    // Universal decoration sections
    data object SectionDivider : GoodsDetailListItem() // Responsibility: Divider between sections

    // Review and store sections
    data class Review(val state: GoodsDetailReviewState) : GoodsDetailListItem() // Responsibility: Display user review summary (rating, review count)
    data class Shop(val state: GoodsDetailShopState) : GoodsDetailListItem()     // Responsibility: Display store info (name, rating, customer service)

    // Product detail sections
    data object DetailsTitle : GoodsDetailListItem()                       // Responsibility: Display "Product Details" title
    data class DetailImage(val imageUrl: String) : GoodsDetailListItem()   // Responsibility: Display one detail image

    // Recommendation sections
    data object RecommendTitle : GoodsDetailListItem()                     // Responsibility: Display "Recommended for You" title
    data class RecommendProduct(val product: BrowseProduct) : GoodsDetailListItem() // Responsibility: Display single recommended product

    // Footer section
    data object ListFooter : GoodsDetailListItem() // Responsibility: List footer placeholder/loading complete indicator
}

Why is this better than traditional approaches?

Eliminates "God layouts" completely: No nested ScrollView or LinearLayout
Each list item can be developed, tested, and iterated independently
Adding a new UI section only requires adding a new subclass, no existing code needs modification

II. Data Layering: Raw Data → UI State — Encapsulating Data Conversion with Mapper

[Mapper Responsibility:] Responsible for converting backend raw data into immutable state objects directly usable by the UI layer. It contains no business logic and is a pure function that takes raw data and outputs UI state.

With list item bricks defined, we need to prepare data for each brick. To reduce coupling between UI and backend data models, we introduce a data conversion layer (Mapper) to produce data for individual list item bricks.

object GoodsDetailProductSectionMapper {
    // Responsibility: Convert GoodsDetail backend model + user selections (specifications, quantity) into UI state for product basic sections
    fun from(
        detail: GoodsDetail,
        shipFromCity: String?,
        selectedWeightIndex: Int,
        selectedFlavorIndex: Int,
        quantity: Int,
    ): GoodsDetailProductSectionState {
        val selectedSku = detail.skus.getOrNull(selectedWeightIndex) ?: detail.skus.firstOrNull()
        val priceYuan = selectedSku?.priceYuan ?: "98.00"
        val formattedPrice = formatDisplayPrice(priceYuan)
        // ... other field mappings
        return GoodsDetailProductSectionState(
            priceYuan = formattedPrice,
            title = detail.title,
            weightSpecs = detail.skus.map { it.name },
            // ...
        )
    }
}

Core Value:

Isolate backend changes: If backend changes field names, only Mapper needs modification, UI layer is completely unaffected
Unified data format: All UI formatting logic is centralized in Mapper
Complete decoupling: UI layer only depends on UI state, not any backend data models

III. Dynamic Assembly: Assembler — The Instruction Manual for Bricks

[Assembler Responsibility:] Responsible for dynamically assembling the final list item sequence based on current state (product info, recommendation list, experiment flags, etc.). It determines which sections to display and in what order — the page's "assembly workshop."

If list items are bricks, then Assembler is the Lego instruction manual. It tells us which bricks to use, in what order, and how to assemble them.

object GoodsDetailListAssembler {
    // Responsibility: Assemble complete list items based on input section states
    fun build(
        productSection: GoodsDetailProductSectionState,
        detail: GoodsDetail,
        detailImageUrls: List<String>,
        recommendProducts: List<BrowseProduct>,
        showListEndFooter: Boolean,
    ): List<GoodsDetailListItem> {
        val items = mutableListOf<GoodsDetailListItem>()

        items += GoodsDetailListItem.PriceMarketing(productSection)
        items += GoodsDetailListItem.ProductTitle(productSection)
        items += GoodsDetailListItem.ServiceSales(productSection)
        items += GoodsDetailListItem.SectionDivider
        items += GoodsDetailListItem.AfterSales(productSection)
        items += GoodsDetailListItem.SectionDivider
        items += GoodsDetailListItem.SpecSelection(productSection)
        items += GoodsDetailListItem.PurchaseQuantity(productSection)

        items += GoodsDetailListItem.SectionDivider
        items += GoodsDetailListItem.Review(GoodsDetailReviewMapper.from(detail))
        items += GoodsDetailListItem.SectionDivider

        items += GoodsDetailListItem.Shop(GoodsDetailShopMapper.from(detail))
        items += GoodsDetailListItem.SectionDivider
        items += GoodsDetailListItem.DetailsTitle
        detailImageUrls.forEach { url ->
            items += GoodsDetailListItem.DetailImage(url)
        }

        items += GoodsDetailListItem.RecommendTitle
        recommendProducts.forEach { product ->
            items += GoodsDetailListItem.RecommendProduct(product)
        }

        if (showListEndFooter) {
            items += GoodsDetailListItem.ListFooter
        }

        return items
    }
}

This Assembler solves multiple pain points of traditional architecture:

Pain Point	Assembler Solution
Dynamicity	Dynamically determine which sections to display based on backend data, AB tests, user identity
Configurability	Adjusting section order only requires moving two lines of code, no UI logic changes needed
Decoupling	Sections are dynamically assembled, naturally avoiding logic being coupled inside specific sections
Testability	Pass different parameters to verify different assembly results without launching the App

IV. ViewModel: Pure State Coordinator

[ViewModel Responsibility:] Acts as a page-level state holder and coordinator. It contains no UI logic and no complex business logic — only responsible for:

Holding page data (LiveData/StateFlow)
Receiving user operations from View (e.g., clicking specifications, modifying quantity)
Calling Mapper and Assembler to generate new UI state
Exposing state to View for observation

class GoodsDetailViewModel : ViewModel() {
    private val repository = GoodsRepository()

    private val _detail = MutableLiveData<GoodsDetail>()
    val detail: LiveData<GoodsDetail> = _detail

    private val _listItems = MutableLiveData<List<GoodsDetailListItem>>()
    val listItems: LiveData<List<GoodsDetailListItem>> = _listItems

    private val _detailImageUrls = MutableLiveData<List<String>>()
    val detailImageUrls: LiveData<List<String>> = _detailImageUrls

    private var selectedWeightIndex = 0
    private var selectedFlavorIndex = 0
    private var purchaseQuantity = 1

    fun load(spuId: String) {
        viewModelScope.launch {
            val detailResponse = repository.fetchGoodsDetail(spuId)
            _detail.postValue(detailResponse)
            rebuildListItems()
        }
    }

    fun selectWeightSpec(index: Int) {
        selectedWeightIndex = index
        rebuildListItems()
    }

    fun selectFlavorSpec(index: Int) {
        selectedFlavorIndex = index
        rebuildListItems()
    }

    fun incrementQuantity() {
        purchaseQuantity++
        rebuildListItems()
    }

    fun decrementQuantity() {
        if (purchaseQuantity > 1) {
            purchaseQuantity--
            rebuildListItems()
        }
    }

    private fun rebuildListItems() {
        val detail = _detail.value ?: return
        val productSection = GoodsDetailProductSectionMapper.from(
            detail = detail,
            shipFromCity = detail.shipFromCity,
            selectedWeightIndex = selectedWeightIndex,
            selectedFlavorIndex = selectedFlavorIndex,
            quantity = purchaseQuantity,
        )
        val items = GoodsDetailListAssembler.build(
            productSection = productSection,
            detail = detail,
            detailImageUrls = detail.detailImages,
            recommendProducts = emptyList(),
            showListEndFooter = true,
        )
        _listItems.postValue(items)
        _detailImageUrls.postValue(detail.detailImages)
    }
}

The entire ViewModel has a single responsibility and clear logic, making it easy for newcomers to understand.

V. Activity: A Thin Shell — The Glue Layer Between Architecture and View

[Activity Responsibility:] Serves as the interaction entry point between the page and Android system, responsible for:

Initializing view binding (setContentView)
Setting up RecyclerView, Adapter, and other UI components
Forwarding user click events to ViewModel
Observing LiveData in ViewModel and updating UI

Activity is not "just a container"; it's an important glue layer between architecture and the Android view system. In Lego Architecture, we still respect Activity's role as navigation and lifecycle manager, but delegate all specific UI assembly and business logic to bricks — ensuring Activity never bloats.

The final Activity code is clean and clear:

@Route(path = RouterConstants.GOODS_DETAIL)
class GoodsDetailActivity : BaseActivity() {

    private lateinit var binding: ActivityGoodsDetailBinding
    private val viewModel: GoodsDetailViewModel by lazy {
        ViewModelProvider(this)[GoodsDetailViewModel::class.java]
    }
    private val imageAdapter = GoodsImagePagerAdapter()
    private lateinit var detailAdapter: GoodsDetailAdapter

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityGoodsDetailBinding.inflate(layoutInflater)
        setContentView(binding.root)

        setupReviewListPanel()
        setupDetailRecyclerView()
        setupScrollToTop()
        setupTopBarScroll()
        setupActions()
        setupPager()
        observeViewModel()
        loadData()
    }

    private fun observeViewModel() {
        viewModel.detail.observe(this) { detail ->
            currentDetail = detail
            currentReviewState = GoodsDetailReviewMapper.from(detail)
            imageAdapter.submit(detail.bannerImages)
            updateImageCount(position = 0, total = detail.bannerImages.size)
        }
        viewModel.listItems.observe(this) { items ->
            val imageUrls = viewModel.detailImageUrls.value.orEmpty()
            if (imageUrls.isNotEmpty()) {
                detailAdapter.submit(items, imageUrls)
            }
        }
        viewModel.detailImageUrls.observe(this) { imageUrls ->
            val items = viewModel.listItems.value
            if (!items.isNullOrEmpty() && imageUrls.isNotEmpty()) {
                detailAdapter.submit(items, imageUrls)
            }
        }
    }
}

The entire Activity only does three things:

Initialize views and Adapter
Forward user click events to ViewModel
Observe ViewModel state and update UI

VI. Independent Components

6.1 Grid Spacing Decoration

[Responsibility: GridSpacingDecoration] A universal RecyclerView grid spacing decorator responsible for adding equal outer margins to each item in grid layouts. Placed in the common module, it can be directly reused in any project requiring grid layouts.

6.2 Review Panel: Minimally Intrusive Page Composition

In the product detail page, the review list is a complex independent feature, but we want it not to affect the main page's simplicity. Through a side panel + Fragment approach, we achieve minimally intrusive page composition.

Core Components and Responsibilities:

Component	Responsibility
`ReviewListPanelController`	Controls panel animations (show/hide), manages Fragment addition/removal
`GoodsReviewListFragment`	Independently hosts complete review list UI and interaction logic
`GoodsReviewListAdapter`	RecyclerView Adapter for review list, responsible for rendering each review
`GoodsDetailReviewMapper`	Converts detail data to UI state needed by review panel

Lego Thinking in Action:

Completely Independent Fragment: Review functionality is fully encapsulated in GoodsReviewListFragment, containing complete list logic

class GoodsReviewListFragment : Fragment() {
    private val listAdapter = GoodsReviewListAdapter()

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        binding.rvReviewList.layoutManager = LinearLayoutManager(requireContext())
        binding.rvReviewList.adapter = listAdapter
    }

    fun render(state: GoodsDetailReviewState) {
        binding.tvReviewListTitle.text = getString(R.string.goods_review_section_title_format, state.totalCount)
        listAdapter.submitList(GoodsReviewListMockData.reviews())
    }
}

Clean Controller: Panel controller only handles animations and Fragment management, no business logic

class ReviewListPanelController(
    private val activity: FragmentActivity,
    private val panelRoot: View,
    private val scrim: View,
    private val panel: View,
    private val fragmentContainerId: Int,
) {
    fun show(reviewState: GoodsDetailReviewState) {
        ensureFragment(reviewState)
        // Animation to show panel
    }

    fun hide() {
        // Animation to hide panel
    }
}

Minimal Main Activity: Only needs to initialize Controller, review logic doesn't intrude into main Activity

private fun setupReviewListPanel() {
    reviewListPanelController = ReviewListPanelController(
        activity = this,
        panelRoot = binding.reviewListPanelOverlay.root,
        scrim = binding.reviewListPanelOverlay.reviewListScrim,
        panel = binding.reviewListPanelOverlay.reviewListPanel,
        fragmentContainerId = binding.reviewListPanelOverlay.reviewListFragmentContainer.id,
    )
}

private fun showReviewListPanel() {
    val reviewState = GoodsDetailReviewMapper.from(detail)
    reviewListPanelController.show(reviewState)
}

On-Demand Fragment Creation: Review panel Fragment is only created on first click, no impact on initial screen performance.

Architectural Benefits:

Review functionality can be developed and tested independently
Main Activity contains no review-related UI logic
Panel animations and Fragment management are encapsulated in Controller
Can be easily replaced with other implementations in the future (e.g., full-screen Fragment, BottomSheet)

VII. Project Structure Overview

7.1 Module Directory Tree

androidArch/
│
├── app/                          # Application entry
│   ├── App.kt                    # Application
│   └── MainActivity.kt           # Home page
│
├── common/                       # Common base (can be depended on by all modules)
│   ├── base/
│   │   ├── BaseActivity.kt       # Activity base class (encapsulates analytics, lifecycle)
│   │   └── BaseViewModel.kt      # ViewModel base class
│   │
│   ├── utils/
│   │   ├── ToastUtils.kt         # Global Toast
│   │   ├── StatusBarUtils.kt     # Status bar operations
│   │   └── PaletteColorUtils.kt  # Color extraction
│   │
│   ├── router/
│   │   └── AppRouter.kt         # Route navigation
│   │
│   └── widgets/
│       ├── GridSpacingDecoration.kt   # Universal grid spacing decorator
│       └── IconFontView.kt           # Icon font component
│
├── app_res/                      # Resource center (colors, dimensions, Drawables)
│   ├── res/
│   │   ├── drawable/             # 50+ universal Drawables
│   │   ├── values/colors_*.xml   # Three-layer color system
│   │   └── values/dimens.xml      # Dimension tokens
│   └── assets/iconfont.ttf        # Icon font
│
├── feature-goods/                # Goods module
│   ├── ui/
│   │   ├── GoodsDetailActivity.kt    # Product detail page (main controller)
│   │   ├── GoodsDetailAdapter.kt     # List adapter (14 ViewTypes)
│   │   ├── GoodsDetailListItem.kt    # List item sealed class
│   │   ├── GoodsDetailListAssembler.kt   # List assembler
│   │   ├── GoodsDetailProductSectionMapper.kt  # Data→UI state
│   │   ├── GoodsDetailReviewMapper.kt
│   │   ├── GoodsDetailShopMapper.kt
│   │   ├── ReviewListPanelController.kt  # Review panel controller
│   │   ├── GoodsReviewListFragment.kt   # Review list (independent Fragment)
│   │   └── DetailAnchorTab.kt           # Tab enum
│   │
│   ├── viewmodel/
│   │   └── GoodsDetailViewModel.kt  # State coordinator
│   │
│   ├── model/
│   │   ├── GoodsDetail.kt              # Raw data model
│   │   ├── GoodsDetailProductSectionState.kt  # UI state model
│   │   ├── GoodsDetailReviewState.kt
│   │   └── BrowseProduct.kt
│   │
│   └── data/
│       ├── GoodsRepository.kt          # Data repository
│       └── GoodsDetailMockCatalog.kt   # Mock data
│
├── feature-login/                # Login module
│   ├── ui/LoginActivity.kt
│   ├── domain/UserRepository.kt
│   └── viewmodel/LoginViewModel.kt
│
└── tools/                       # Pure utilities (cross-project reuse)
    └── utils/
        ├── DateUtils.kt
        ├── StringUtils.kt
        └── ValidateUtils.kt

7.2 Core Class Responsibility Description

Module	Class Name	Responsibility	Lines of Code
ui	GoodsDetailActivity	View binding, lifecycle, user interaction forwarding	approx. 500
ui	GoodsDetailAdapter	List rendering for 14 ViewTypes	approx. 400
ui	GoodsDetailListAssembler	Dynamic list item assembly	approx. 80
ui	GoodsDetailListItem	List item type definition	approx. 50
ui	ReviewListPanelController	Review panel animation and Fragment management	approx. 150
ui	DetailAnchorTab	Tab enum (independent small class)	approx. 10
mapper	GoodsDetailProductSectionMapper	Data→Product section UI state	approx. 60
mapper	GoodsDetailReviewMapper	Data→Review section UI state	approx. 30
mapper	GoodsDetailShopMapper	Data→Shop section UI state	approx. 20
vm	GoodsDetailViewModel	Data loading, state holding, trigger rebuild	approx. 150
common	BaseActivity	Encapsulates analytics, Edge-to-Edge	approx. 50
common	GridSpacingDecoration	Universal grid spacing decorator	approx. 40
common	ToastUtils	Global Toast	approx. 30

7.3 Data Flow

Backend Data          Mapper Conversion         Assembler Assembly         ViewModel Holding        Activity Observation
   │                        │                           │                        │                        │
   ▼                        ▼                           ▼                        ▼                        ▼
GoodsDetail ──► GoodsDetailProduct ──► List<GoodsDetail ──► _listItems ─────► notifyDataSetChanged
                SectionState             ListItem>

This practical case fully implements the core principles of Lego Architecture proposed in Article 2:

Minimal Base Classes: GoodsDetailActivity only inherits an empty BaseActivity (handling only essential seams like analytics and lifecycle), with all functionality provided through pluggable bricks.
Infinite Splitting: The page is split into 15+ independent list item bricks, each with a single responsibility; the review panel is split into independent Fragment + Controller.
Tool Iteration: The price formatting method was initially written in feature_goods/utils, then moved to common/utils after review found it was needed by multiple modules — exactly the "Private → Shared" evolution path described in Article 2.

Detailed methodologies on governance thinking, the three stages of tool iteration (Private→Shared→Remote), and reuse discovery were fully explained in Article 2 and won't be repeated here.

VIII. Architecture Advantage Comparison

Dimension	Traditional Approach (Unsplit)	Lego Approach
Code Organization	1 Activity with 3000+ lines	10+ independent components with 100-300 lines each
Maintainability	Changing one thing affects everything	Independent modifications, no cross-component impact
Testability	Difficult to test individually	Each component can be tested independently
Reusability	Almost impossible to reuse	Components can be reused across multiple pages
Extensibility	Adding sections requires changing many places	Adding sections only needs new ListItem and Assembler logic
Parallel Development	Only sequential development possible	Multiple developers can work on different components in parallel

IX. Conclusion: The Ideal Complex Page

An ideal complex page, architecturally speaking, consists of several functional blocks with clear responsibilities and boundaries. Inside each block, you see highly cohesive utility classes and UI components, with minimal scattered glue code. Numerous basic bricks, composite bricks, advanced bricks, and UI components are battle-tested, stable, reliable "technical assets." Ultimately, what was once a bloated complex page becomes robust, elegant, agile, lightweight, extensible, testable, maintainable, and highly readable — like a carefully designed work of art rather than a pile of unmanageable code.

The complete Lego Architecture system can be summarized as:

One Axiom: Divide-and-conquer + Single Responsibility
Multiple Theorems: Governance thinking (big-picture view, logic convergence), tool iteration (Private→Shared→Remote), reuse discovery (small independent particles facilitate scanning and integration)

When you truly build applications with Lego thinking, you realize: Complexity doesn't come from the application itself, but from not splitting it into small enough bricks and lacking continuous governance and iteration.

Of course, mastery of design patterns, code aesthetics, and the ability to spot reusable bricks are also essential qualities of an excellent engineer.

Next Article Preview: We'll continue enriching our demo project and explore how design patterns can serve as the glue for Lego Architecture, making your brick combinations more flexible and robust. See Article 4.

Related Reading:

Modern Android Architecture (Part 2): The Lego Architecture: Divide and Conquer, Taken to the Extreme

goodlords — Mon, 01 Jun 2026 02:06:02 +0000

Series Navigation: Article 1: A Decade of Android Architecture Evolution | Article 3: Refactoring a Product Detail Page with Lego Architecture | Article 4: Design Patterns — The Glue of Lego Architecture

Foreword: The Pain of Bad Code Doesn't Come from Architecture

In the previous article, we discussed that architecture is just "technique" — it only solves the rough partitioning of code, which is far from sufficient. In this article, we face the real pain points in project implementation and propose a practical divide-and-conquer methodology — Lego Architecture.

0. Inspiration: Reflections from the Pain of Architecture Migration

I've gone through three large-scale Android architecture refactorings, each time feeling like I've shed a layer of skin:

From MVC to MVP: The team spent two months creating a heavy set of BaseActivity / BaseFragment / BasePresenter.
From MVP to MVVM: All Base classes had to be rewritten, a large number of utility classes deeply coupled with Base were forced to change, affecting 40% of business code.
When MVI started to become popular, we were completely exhausted.

What made us so passive? Is migrating to MVI a one-time solution? Will future architectures like MV-Whatever repeat this nightmare? If migration is inevitable, which code can remain unchanged?

This pain forced us to ask a fundamental question: What is the ultimate answer to architecture?

Sitting in front of my computer, I suddenly remembered the Lego bricks I played with as a child.

Why can a few basic bricks build houses, cars, spaceships? Why can bricks from 10 years ago still perfectly fit with new sets?
At that moment, I seemed to see the answer to all architectural problems.

The most amazing thing about Lego is not the cool finished products, but those basic 1×1 and 2×4 bricks:

Only a few studs and tubes, no predefined functions.
Follow a globally unified connection standard, perfectly compatible with any other Lego brick.
Can be used anywhere in any model.
Interface specifications have never changed since 1958.

In contrast, those specialized parts designed for specific models — like the curved hull of the Millennium Falcon — are almost useless outside of that one model. Once removed, they become waste.

Lego's core philosophy is: Minimum granularity = Maximum reusability = Maximum flexibility.
Specialized parts become useless outside their model. The same principle applies to code reuse.

From this, we've distilled a software engineering approach called Lego Architecture — it doesn't aim to replace MVVM or MVI, but provides a set of programming philosophies and engineering disciplines about "how to split, how to accumulate, how to govern."

I. Base Classes: Avoid If Possible, Keep Minimal If Necessary

In the three architecture refactorings, what pained me the most wasn't business logic, but those seemingly "convenient" Base classes.

What's the problem? We tied too many unnecessary things to Base.

1.1 The Correct Use of Base: Avoid If Possible

Base classes have only one valid reason to exist: Provide a seam for lifecycle-related capabilities needed by 90% of pages.

For example:

Automatic page entry/exit tracking for analytics
Callback distribution for permission requests

Beyond that, no business logic, page initialization order, or utility class references should go into Base.

1.2 Strongly Disliked: Constraining Page Initialization Workflow in Base

I've seen Base classes like this:

abstract class BaseActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initCallerData()
        initView()
        initPageData()
        initObservers()
    }
    abstract fun initView()
    abstract fun initPageData()
    abstract fun initCallerData()
    abstract fun initObservers()
}

This is violent constraint on subclasses. When you don't know the initialization order desired by upper-level pages (some want to initialize observers first, others want to initialize views first), this template method becomes a shackle and source of redundant confusion.

Good Base classes shouldn't dictate order, only provide optional capabilities. Even initView shouldn't exist — let each page write its own initialization in onCreate, making it clear and explicit.

1.3 Pluggable Bricks Instead of Base

Observation reveals that Base classes often contain many methods or code blocks that could be in xxxUtils — permission requests, soft keyboard management, network detection... They're stuffed into Base only because "multiple pages need them," not because they're truly lifecycle-related.

Better approach: Base is just an empty shell; all functionality is provided through pluggable bricks.

For example, if you need permission request capability, instead of writing it in Base, use an independent PermissionHelper directly where needed:

class PermissionHelper(private val activity: AppCompatActivity) {
    fun request(permission: String, onGranted: () -> Unit) { ... }
}

Any page, Fragment, or Dialog can use this brick directly without depending on inheritance. Base can even be an open class with nothing inside.

II. From Coarse-Grained to Extreme Divide-and-Conquer: Lego Principles

All mainstream architectures in the industry (MVC, MVP, MVVM, MVI, Clean Architecture...) essentially embody divide-and-conquer thinking — they split code by responsibility, layer, or data flow.

But their granularity is usually coarse:

A layer (View, ViewModel, Model)
A module (feature, domain, data)
A role (Presenter, UseCase)

They don't answer a crucial question: How fine-grained should we split?

Lego bricks provide a physical-world answer: keep splitting until reaching indivisible basic particles. A 2×4 brick has a unified interface, can be used anywhere in any Lego model, and hasn't changed in 68 years.

Lego Architecture is the ultimate practice of divide-and-conquer thinking: not just splitting at the MVX level, but splitting infinitely across all levels and dimensions until each unit does only one thing, with stable interfaces and no redundant functionality.

This principle can be applied to:

UI layer: Each ViewHolder of a RecyclerView is an independent brick
Logic layer: Each UseCase encapsulates only one business scenario
Utility layer: Each utility method does only one thing
State layer: Each State describes only one independent domain

The stopping condition for splitting is simple: stop when you can't give the unit a smaller, more accurate name. If a class or method name contains words like "and", "with", or "as well as", it means it can be split further.

This is the fundamental difference between Lego Architecture and other architectures:

Other architectures tell you "which layer code should go to".
Lego Architecture tells you "how small code should be split and how to keep splitting".

III. Splitting Examples Under Lego Thinking

Let's look at some concrete examples of how code is split into minimal particles following Lego principles.

3.1 Utility Classes: From Kitchen Sink to Atomic Bricks

Counterexample: A DateUtils with a dozen methods for time formatting, timestamp conversion, relative time calculation, timezone handling... hundreds of lines of code.

Lego Split:

DateFormatUtils: Only formats dates into strings
TimestampConverter: Only converts between timestamps and date objects
RelativeTimeCalculator: Only calculates "just now", "a few minutes ago", etc.
TimeZoneHelper: Only handles timezone-related operations

Each class has a single responsibility, clear method names, and is easy to test and reuse.

3.2 ViewModel: From God Object to Service Composition

Counterexample: A HomeViewModel containing carousel data, recommendation lists, user info, shopping cart count, notification unread count... 5000 lines of code, changing one place may affect unrelated fields.

Lego Split:

HomeBannerViewModel: Only responsible for carousel data
HomeRecommendViewModel: Only responsible for recommendation lists
ShoppingCartViewModel: Universal service, reusable across multiple pages
NotificationViewModel: Universal service, reusable across multiple pages

Combined usage in Activity:

private val bannerVM: HomeBannerViewModel by viewModels()
private val cartVM: ShoppingCartViewModel by viewModels()
private val notificationVM: NotificationViewModel by viewModels()

Each ViewModel can be independently tested and reused. Even ShoppingCartViewModel can be observed simultaneously in product detail pages, cart pages, and home pages.

3.3 Intent/MVI State: From Explosion to Grouping

Counterexample: A HomeIntent sealed class stuffed with 200+ intents, including carousel clicks, recommendation list load more, user avatar clicks...

Lego Split: Align Intents with ViewModels, each ViewModel corresponds to an Intent group.

sealed class BannerIntent {
    object Load : BannerIntent()
    data class Click(val position: Int) : BannerIntent()
}
sealed class RecommendIntent {
    object LoadMore : RecommendIntent()
    data class Click(val item: RecommendItem) : RecommendIntent()
}

Same for State: Instead of stuffing all fields into one HomeState, split into BannerState, RecommendState, etc., with each ViewModel managing its own state.

3.4 UseCase: One Class Per Scenario

Counterexample: UserUseCase with five unrelated operations: login, register, change password, get user info, upload avatar...

Lego Split: Each UseCase encapsulates only one complete business scenario.

LoginUseCase
RegisterUseCase
UpdatePasswordUseCase
FetchUserInfoUseCase

This way, any page only needs to depend on the UseCase it needs, not the entire kitchen sink.

IV. Discovery and Iteration of Utility Classes: Good Bricks Grow Naturally

Bricks in Lego Architecture aren't designed in one go; they emerge naturally during continuous development and refactoring — essentially a process of evolving from specialized parts to basic parts.

4.1 Private Bricks: Write as You Use

During feature development, you find a piece of logic that can be encapsulated (like a price formatting method), but you're unsure if it's universal. Write it in the current module's utils package as a private brick.

// feature_goods/utils/PriceFormatUtils.kt
internal fun formatPrice(priceYuan: String): String = "¥$priceYuan"

It's only used within this module and not exposed to other modules.

4.2 Shared Bricks: Regular Review, Extract for Reuse

The project conducts a review refactoring every quarter. The team scans private utilities under each feature_xxx/utils, finds classes that are used by at least two modules or clearly have universal value, and moves them to the common/utils module to become shared bricks.

Meanwhile, the original private bricks disappear (or become thin, leaving only a delegation to the shared brick). This step requires unit testing and Code Review to ensure no functionality is broken during the move.

4.3 Remote Bricks: Battle-Tested, Become Assets

After a shared brick has been used online for half a year or a year and proven stable by millions of users, it can be extracted from the common module, published to a Maven repository, and become a remote brick for all company projects to depend on directly.

At this point, it becomes a "write-once, use-forever tool" — like StringUtils, NetworkUtils, ScreenUtils. You'll never need to rewrite them; just upgrade the version number.

4.4 Why Must We Split to Minimum Granularity?

Because only when split small enough can you easily spot during regular scans: "Oh, this formatting and that formatting can be merged" or "This validation logic has appeared three times." If they're scattered in hundreds-of-lines classes or duplicated across different Activities, you'll never find reuse opportunities.

The infinite splitting in Lego Architecture isn't for splitting's sake; it's to make reuse opportunities visible, turning 'passive discovery' into 'active scanning'.

V. Conclusion: Lego Architecture, Embracing Change with Stability

Lego Architecture isn't meant to replace your existing MVVM or MVI; it's a set of programming disciplines and governance philosophies that require you to do the following on top of any architecture:

Minimal Base Classes: Avoid if possible; if unavoidable, only include the most basic lifecycle seams, never dictate initialization order.
Infinite Splitting: Split code across all levels (UI, logic, state, utilities) into the smallest stable particles until each unit does only one thing.
Continuous Utility Iteration: Private → Shared → Remote, letting good bricks grow naturally and eventually become "write-once" technical assets.

When you truly achieve these, you'll find:

Architecture migration is no longer a disaster: Base classes are thin shells, business logic is in pluggable bricks, changing architecture only changes the container.
Code reuse is no longer a slogan: Minimum granularity naturally drives reuse; someone may have already provided a remote brick before you even write it.
Maintenance costs drop exponentially: Each brick has a single responsibility, changes don't ripple to unrelated areas.
Team collaboration is easy: Newcomers only need to learn brick usage, not understand thousands of lines of god classes.

This is Lego Architecture — the ultimate practice of divide-and-conquer, a methodology that embraces change with stability.

Next Article Preview: We'll use a real e-commerce App product detail page to demonstrate the complete process of Lego Architecture from splitting to assembly.

Related Reading:

Modern Android Architecture (Part 1): A Decade of Android Architecture Evolution: What Problem Are We Really Solving?

goodlords — Mon, 01 Jun 2026 02:05:31 +0000

Series Navigation: Article 2: The Lego Architecture: Divide and Conquer, Taken to the Extreme | Article 3: Refactoring a Product Detail Page with Lego Architecture | Article 4: Design Patterns — The Glue of Lego Architecture

Foreword: After Learning All Architectures, Did Our Code Actually Get Better?

Since Android's birth in 2010, mainstream architectures have undergone at least five industry-level iterations. We've memorized MVC's layering, mastered MVP's interface decoupling, embraced MVVM's data binding, praised Clean Architecture's dependency inversion, and now we're all turning to MVI's unidirectional data flow.

But here's the gut-wrenching question: After learning and refactoring with all these architectures, has our code actually gotten better?

If your answer is "No" — or even "We just moved the garbage code to a different place" — then this article is for you.

I. The Essence of Architectural Evolution: A Revolution to "Reduce Connections"

Understanding all architectural evolution requires only one extremely simple model: The number of strong reference connections determines system complexity.

The more connections there are, the deeper the dependencies between modules, and the more likely changes will trigger cascading reactions. Throughout history, all architectures have been doing the same thing — reducing connections as much as possible to make dependency relationships unidirectional and clear.

1. MVC: The Confused Triangle (6 connections)

As the originator of modern architecture, MVC first proposed the idea of layering:

Model: Data
View: UI
Controller: Logic

However, in classic implementations, all three layers interact with each other, forming a closed triangle with a total of 6 strong reference connections:

View ←→ Controller ←→ Model
↑                       ↑
└───────────────────────┘

In Android, Activity/Fragment acts as both View and Controller, leading to the common "Massive View Controller" with thousands of lines. A single data change can affect all layers, making it nearly impossible to understand the flow.

2. MVP: Cutting Direct Connections (4 connections)

MVP made a revolutionary simplification: Completely prohibit direct interaction between View and Model.

All cross-layer communication must go through Presenter. The triangle is broken, becoming a linear dependency:

View ←→ Presenter ←→ Model

Connections reduced from 6 to 4, a 33% complexity reduction. View only displays, Model only handles data, and business logic lives entirely in Presenter. Between 2015-2018, this almost saved the entire Android development community.

3. MVVM: Dependency Inversion (3 connections)

Building on MVP, MVVM introduced data binding and observable states to achieve dependency inversion:

View → ViewModel ←→ Model

View still holds a ViewModel reference, but ViewModel no longer holds any View references.
After completing a task, ViewModel only updates an observable data state, completely unaware and unconcerned about who is observing.

Connections reduced to 3. The relationship between View and ViewModel becomes unidirectional, eliminating manual UI update code and tedious interface definitions.

The deeper value of this change: ViewModel becomes a reusable mediator (or service provider), observable and reusable by any view. Multiple ViewModels can naturally serve a single view. Compared to Presenter, ViewModel has smaller granularity and higher reusability.

These improvements made MVVM quickly replace MVP as the mainstream.

4. MVI: Unidirectional Closed Loop (3 connections + strict unidirectional flow)

MVI is the latest evolution. Building on MVVM, it completely straightens the data flow:

All user operations are aggregated into a single Intent
All UI states are aggregated into an immutable State
Data flows in a strict unidirectional cycle: User Action → Intent → ViewModel → Model → New State → View Rendering

From a reference perspective, both MVI and MVVM have 3 connections. But MVI enforces: Any state change must go through ViewModel; View cannot directly modify data.

This brings significant engineering benefits:

Centralized state management for full visibility of page behavior
Immutable state prevents accidental modifications
Predictable behavior for easy debugging and logging
Advanced features like time-travel debugging and unified logging

However, MVI has fatal implementation barriers. It requires extremely high abstraction skills from developers. When programmers lacking splitting awareness use MVI, they fall into three typical traps:

Intent Explosion: A complex page defines 200+ Intents with long, smelly names and overlapping responsibilities, making maintenance harder.
God State: A single State object stuffed with 30 unrelated fields, where changes trigger cascading updates.
Mesh Dependencies: Multiple Intents call each other, forming chaotic call chains that make the unidirectional flow meaningless.

What should be a rigorous finite state machine becomes an "infinite state machine" — this is why MVI is seen as a disaster by some.

II. Architecture is Just "Technique": It Can't Stop You from Writing Bad Code

I've seen many absurd projects:

Using advanced MVVM but writing 5000-line ViewModels (architecture can't control internal bloat)
Strictly following Clean Architecture but filling the Domain layer with business coupling (architecture can't control UseCase boundaries)
Insisting on MVI's unidirectional flow but mixing carousel data, recommendation lists, and user info in one State (architecture can't control State granularity)

Bad programming habits don't disappear just by switching architectures. We merely moved garbage from Activity to Presenter, then to ViewModel, then to UseCase. We just moved garbage from one room to another without actually cleaning it up.

Take the same login logic:

In MVC, it's scattered across the Activity
After refactoring to MVP, it's copied entirely into Presenter, still 300 lines of procedural code
After migrating to MVVM, it's stuffed into a LoginViewModel, with the login() method still a mess
Converting to MVI, it becomes a jumble of Intents and States, appearing unidirectional on the surface but with tangled logic underneath

Architecture is "technique". It only solves the "rough partitioning" of code, specifying where View, ViewModel, and Model should go. But it can't tell you how fine-grained to split code within the same layer, how to organize it, or how to reuse it. What truly improves code quality includes at least:

Programming Philosophy: Fundamental principles like divide-and-conquer, abstraction, and single responsibility determine how we view and decompose problems.
Code Hygiene: Zero tolerance for redundant code, poor naming, and out-of-bounds logic keeps the codebase healthy long-term.
Programming Literacy: Habits and awareness of writing readable, testable, maintainable code make collaboration painless.
Scientific Implementation: Practical tool encapsulation strategies, governance processes, and iteration mechanisms ensure ideas are truly executed.

These are the foundational skills and qualities of an excellent engineer. Engineers with these abilities can write clean, robust, evolvable code without relying on any "silver bullet architecture."

Related Reading:

Modern UI Architecture (Part 4): Design Ownership and Team Rollout

goodlords — Tue, 19 May 2026 05:24:06 +0000

现代化 UI 架构总结：设计主权回归与团队落地

本文是 UI 架构系列的第四篇，也是最后一篇。建议先阅读第一篇：三层颜色体系与系统化设计方案、第二篇：Drawable 层规范与工程实践、第三篇：Style 层如何系统性消除代码冗余了解完整架构体系。

一、架构全景：

在前面三篇文章中，我们构建了一套完整的 UI 资源架构体系：

1.1 架构的核心价值

层级	核心价值	解决的问题
Style	消除冗余，提升复用	重复属性定义
Drawable	统一形态，状态管理	视觉不一致
Func_*	语义抽象，职能归一	颜色滥用
基础色+主题	主题切换，灵活适配	多模式支持

1.2 Demo 的局限性

需要说明的是，本仓库中的 demo 仅作为抛砖引玉：

颜色覆盖：只实现了常用 token 子集；矩阵补全、新增档位均由设计师在资源文件中维护，研发不自行扩展
Drawable 资源：仅实现了按钮、输入框等基础组件的状态，实际项目会更复杂
组件覆盖：demo 覆盖常用 token 子集（表面层级、填充/渐变、按钮形态与禁用态等），列表、弹窗等复杂场景仍需按产品扩展

1.3 Demo 运行效果（日间 / 夜间）

仓库内置 Token 样例 页（activity_token_showcase），用于对照资源命名与真机效果：右上角切换深浅色后，同一套 func_* / Drawable / Style 无需改代码，仅由 values-night 中 t_* 映射驱动换肤。

日间	夜间

GitHub 预览（可点击查看原图）：

日间：screenshot/day.png
夜间：screenshot/night.png

左：values 日间映射；右：values-night 覆写 `t_` 后的同一页面。*

这套架构的真正价值在于方法论，而非具体实现。

二、深度思考：UI 架构的权力究竟属于谁？

2.1 一个尖锐的问题

UI 架构的权力究竟属于设计师还是属于程序员？

这个问题困扰了无数团队。让我们从几个角度分析：

角色	优势	劣势
顶尖设计师	具备专业视觉素养，理解设计语言，追求极致细节	对技术实现边界不了解，难以落地
程序员	懂技术实现，能落地，但良莠不齐	缺乏设计专业训练，视觉敏感度不足

2.2 现实的困境

在大多数公司，现状是：

设计师设计稿 → 精心设计的颜色、间距、阴影
研发实现 → 代码实现时可能随意选择颜色、调整尺寸
反复 UI 走查 → 发现偏差，返工修改
再次走查 → 仍有偏差，继续返工

这是一个巨大的资源浪费循环。

2.3 浪费有多大？

根据我在多个中等规模项目中的经验，常见情况是：

单次 UI 走查：往往能发现数十处视觉偏差（色值、字号、间距不一致）
走查轮次：往往要 3–5 轮才能收敛
每轮修复：往往占用 1–2 人天研发 + 设计师复核时间

叠加产品经理协调、测试回归、上线推迟，单个项目就会白白消耗数人天到数十人天。团队项目一多，这就是持续燃烧的隐性成本。

三、解决方案：将定义权交还给设计师

3.1 架构的使命

这套 UI 架构体系的深层使命，是将 UI 的定义权从程序员手中重新夺回到设计师手中。

核心思路：

设计语言标准化：由设计总监定义完整的设计语言
资源文件可配置化：将设计决策转化为可配置的资源文件（所有权在设计侧）
代码引用规范化：程序员只引用已有 token 与 Style，无权自行定义颜色、字号、圆角档位或新增 Style 变体

3.2 设计师主导的工作流

具体实现：

设计阶段：设计总监定义设计语言
- 颜色体系（7大色系 × 6种职能）
- 文字规范（字号、字重、行高）
- 间距系统（8dp 栅格）
- 组件规范（按钮、卡片、输入框）
配置阶段：将设计语言转化为资源文件
- colors_primitives.xml：基础色定义
- colors_theme_tokens.xml：主题映射
- colors_semantic.xml：功能色定义
- styles_tv.xml：文字样式
- styles_button.xml：按钮样式
- drawable/*：状态选择器
开发阶段：程序员只需引用

   <TextView style="@style/tv_black_1_size_15" />
   <Button style="@style/Btn.Orange.Capsule.Emphasis" />

3.3 权力回归的意义

维度	设计师主导	程序员主导
视觉一致性	高度一致，符合设计语言	参差不齐，取决于个人水平
设计还原度	100% 还原设计意图	60-90%，取决于专业能力
迭代效率	改资源文件即可，无需改代码	需要修改大量代码
维护成本	低，集中管理	高，分散在各处

四、统一架构带来的深远影响

4.1 世界级的产品外观

统一的 UI 架构带来的是世界级的产品外观设计和视觉一致性。

举个例子：同样是"灰色"，细微的差异就会导致 App 的品质感天差地别：

设计稿：gray_2 = #8A8A8A（精心调配的中性灰）
错误实现：gray = #888888（随手写的灰色）

这 0.5% 的差异，在用户眼中就是"专业"和"山寨"的区别。

4.2 团队协作效率提升

场景对比：

场景	传统方式	架构方式	效率提升
新增页面	手动写所有属性	引用 style，一行搞定	80%
修改主题色	修改所有布局文件	修改一处资源	99%
UI 走查修复	查找并修改多处	资源已定义，无需修改	100%

4.3 品牌形象的统一

在多端、多产品线的场景下，统一架构的价值更加凸显：

Android/iOS/Web：使用相同的颜色定义
主 App/小程序/H5：保持一致的视觉风格
不同版本：确保品牌形象的连续性

五、架构落地的实践建议

5.1 渐进式落地策略

5.2 团队协作规范

设计规范先行：设计总监必须先定义设计语言
资源配置同步：所有颜色/字号/Style/Drawable 变更仅由设计侧提交资源 PR
代码审查把关：研发 PR 禁止硬编码颜色、尺寸，禁止新增 func_* / tv_* / Btn.*
定期审计：CI 门禁 + 设计走查，发现违规引用一律打回

5.3 工具链支持

建议配套以下工具：

设计稿标注工具：Zeplin、Figma 插件
资源生成工具：自动从设计稿生成资源文件
代码检查工具：Lint 规则检查硬编码
预览工具：实时预览主题切换效果

六、系列文章回顾与总结

6.1 四篇文章的核心贡献

文章	核心内容	解决的问题
第一篇	三层颜色体系与系统化设计方案	主题切换、颜色一致性、职能 token
第二篇	Drawable 层规范与工程实践	形态定义、状态管理
第三篇	Style 层如何系统性消除代码冗余	消除冗余、提升复用
第四篇	设计主权回归与团队落地	权力边界、规范强制执行

6.2 架构的核心原则

分层抽象：从基础色到组件，逐层抽象
语义化命名：让资源名表达用途，而非具体值
正交组合：属性分离，灵活组合
集中管理：资源集中定义，便于维护

6.3 最终价值

这套架构体系带来的价值是系统性的：

对用户：更一致、更专业的产品体验
对设计师：设计意图得到完整还原
对程序员：减少重复劳动，提升开发效率
对公司：节省大量人力成本，提升品牌形象

七、跨平台适用性与 AI 时代的设计交付

需要强调的是，这套 UI 架构虽然以 Android 作为例子说明，但核心思想可以完全平移到 iOS、React、H5、小程序等任何平台。架构的本质是"设计语言的工程化表达"，与具体实现技术无关。

在 AI 大模型的帮助下，设计师可以交付完整的一套 UI 架构。这套架构是 AI 友好的——通过合理的 Prompt、设计规范与资源清单，能够快速沉淀全平台统一的设计语言。

最重要的一点：程序员没有权力定义颜色、样式、字号、按钮，也没有权力「扩展档位」或私自新增 token。需要新色、新字号、新 Style 时，必须回到设计师维护的资源文件（本体系中的 colors_*.xml、styles_*.xml、drawable/）由设计侧变更，再合入工程。程序员的职责只有一项：严格引用设计师已发布的资源，确保设计意图完整落地。

八、规范门禁：让权力回归不只停留在纸面上

架构写得再漂亮，若缺少可执行的约束，仍会回到「谁写页面谁说了算」的老路。所谓门禁，并不是为难研发，而是把前文所说的设计主权固化进团队的日常流程：该谁定的已经定好，研发只做引用与实现。

8.1 建议守住的四条底线

颜色只能来自设计 token：页面里不应出现随手写的色值，也不应绕过功能色层去碰主题层、基础色。
文字与按钮必须走设计样式：字号、字色、按钮形态等，应在设计侧资源中选型，而不是在页面里临时拼凑。
禁止重复定义已规范化的属性：同一类控件的表现，应通过样式体系统一，避免「这个页面特殊、那个页面例外」。
变更入口唯一在设计侧：需要新色、新档位、新样式时，由设计师更新资源与规范，研发提需求、不自行扩库。

8.2 如何落地

合并前审查：把 UI 资源是否符合规范，纳入 Code Review 的固定项；关键版本可由设计同学参与走查或签字。
设计资源即唯一真相：颜色、样式、Drawable 等集中由设计维护的资源包发布，业务工程只依赖已发布版本，避免各端各写一套。
自动化作为兜底：团队可按需要配置静态检查或流水线卡点，但目的始终是拦截越权定义，而不是堆砌技术细节。
违规即打回：一旦在页面里发现临时色、临时字号、临时按钮样式，应退回并要求回到设计 token 与样式体系，而不是在评审会上「差不多就行」。

8.3 门禁真正要达成的效果

设计师的权威性：视觉语言由设计定义，研发不再充当「第二设计师」。
规范的刚性：越权改动进不了主干，减少靠人记、靠自觉的侥幸。
产品的一致性：用户在不同页面、不同版本里，看到的是同一套品牌与品质感。

门禁不是冷冰冰的流程，而是对前文「权力回归」的制度保障。当设计与研发都认同这套边界，UI 走查才会从「找茬大战」变成「按图验收」。

九、结语

UI 架构不是简单的"颜色配置"，而是设计语言的工程化落地。

它解决的核心问题是：如何让设计师的专业决策能够在代码中完整、一致地体现。

在这个过程中，程序员的角色从「视觉决策者」转变为「实现执行者」：颜色、字号、样式、按钮形态的定义权完全在设计侧；程序员的价值体现在正确引用资源、业务逻辑与性能优化——而不是在布局里「顺手改个色」。

希望这套架构体系能够为你的团队带来启发，让我们一起构建更好的产品体验。

系列文章回顾：

参考代码：

完整实现仓库

💡 如果这套架构对你有帮助，欢迎点赞、收藏、转发。关注我，获取更多Android架构设计干货。

Modern UI Architecture (Part 3): The Style Layer and Eliminating Redundancy

goodlords — Tue, 19 May 2026 05:16:54 +0000

现代化 UI 架构：Style 层如何系统性消除代码冗余

本文是 UI 架构系列的第三篇，建议先阅读第一篇：三层颜色体系与系统化设计方案、第二篇：Drawable 层规范与工程实践了解核心设计理念。

前言

在多年的 Android 开发实践中，我发现一个普遍存在的问题：TextView 的属性定义存在大量重复。

打开任何一个中等规模的 Android 项目，你会发现几乎每个布局文件中都有类似这样的代码：

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:textColor="@color/black"
    android:textSize="15sp"
    android:includeFontPadding="false"
    android:text="商品名称" />

这些属性被重复定义了成千上万次。想象一下：如果你有 500 个 TextView，有一天设计师说所有文字的字号要统一从 15sp 改成 16sp，或者要关闭字体内边距，你需要打开 500 个文件逐个修改——这简直是噩梦。

我们分析了大量项目中的 TextView 使用情况，遵从 98% 的 TextView 的共性，提炼出 3 个必须封装进 tv_base 的基础属性（宽高、includeFontPadding）。

Style 层的核心价值：由设计师在 styles_tv.xml、styles_button.xml 中定义文字与按钮的职能化样式，研发在布局里只引用 tv_*、Btn.*，不再自行决定 textColor / textSize / 按钮形态。

职能 ≠ 业务（系列铁律）：tv_black_1_size_15、Btn.Orange.Capsule.Emphasis 命名的是色系 + 文本层级 / 按钮形态 + 交互档位等 UI 职能，不是「商品标题」「下单支付」等业务场景。业务只决定在哪个页面引用哪条职能样式，不应反过来用业务名定义 Style——否则全公司都会陷入「每个页面一套按钮 Style、改主题改到崩溃」的通病。

跨平台：tv_* / Btn.* 对应 iOS 的 UIFont+语义色组合、Web 的 typography utility class；同样应由设计系统维护，研发只引用。

一、工程实践中的痛点：TextView 属性冗余

1.1 统计数据：一个中等项目的属性重复情况

根据我们对多个项目的分析，一个包含 100 个 Activity/Fragment 的项目：

平均每个布局文件有 5-10 个 TextView
每个 TextView 平均定义 3-5 个重复属性
总重复次数超过 2000 次

1.2 典型的重复模式

<!-- 模式1：每个 TextView 都重复写宽高 -->
<TextView android:layout_width="wrap_content" />
<TextView android:layout_width="wrap_content" />
<TextView android:layout_width="wrap_content" />

<!-- 模式2：每个 TextView 都要设置 includeFontPadding -->
<TextView android:includeFontPadding="false" />
<TextView android:includeFontPadding="false" />
<TextView android:includeFontPadding="false" />

<!-- 模式3：颜色和字号的组合重复 -->
<TextView android:textColor="@color/black" android:textSize="15sp" />
<TextView android:textColor="@color/black" android:textSize="15sp" />
<TextView android:textColor="@color/black" android:textSize="15sp" />

1.3 维护成本分析

场景	无 Style	有 Style	节省比例
修改默认宽高	需要修改所有文件	修改一处	~99%
修改 includeFontPadding	需要修改所有文件	修改一处	~99%
修改字号	需要修改所有文件	修改一处	~99%
修改颜色主题	需要修改所有文件	修改一处	~99%

二、经验总结：TextView 必须的 3 个基础属性

经过多个大型项目的实践验证，我们总结出 TextView 必须定义的 3 个基础属性：

<style name="tv_base">
    <item name="android:layout_width">wrap_content</item>
    <item name="android:layout_height">wrap_content</item>
    <item name="android:includeFontPadding">false</item>
</style>

2.1 为什么是这 3 个？

属性	必要性	工程经验
`layout_width="wrap_content"`	必须	95% 的 TextView 不需要撑满一行，需要时在布局中覆盖
`layout_height="wrap_content"`	必须	文字高度应由内容决定，避免固定高度导致截断
`includeFontPadding="false"`	必须	Android 默认字体有额外内边距，导致垂直居中困难

2.2 为什么不再多定义一些？

<!-- ❌ 不推荐：在 base 中定义过多属性 -->
<style name="tv_base_bad">
    <item name="android:layout_width">wrap_content</item>
    <item name="android:layout_height">wrap_content</item>
    <item name="android:includeFontPadding">false</item>
    <item name="android:textColor">@color/black</item>  <!-- 不应该在这里定义 -->
    <item name="android:textSize">15sp</item>           <!-- 不应该在这里定义 -->
</style>

原因：

正交性原则：颜色和字号是正交的属性，应该分开定义
组合灵活性：不同场景需要不同的颜色+字号组合
单一职责：base 只负责"通用基础属性"，不负责"业务属性"

三、正交组合：颜色 × 字号的高效复用

3.1 设计思路

3.2 色系层定义

<!-- 黑色系（主文本） -->
<style name="tv_black_1" parent="tv_base">
    <item name="android:textColor">@color/func_black_text_1</item>
</style>
<style name="tv_black_2" parent="tv_base">
    <item name="android:textColor">@color/func_black_text_2</item>
</style>

<!-- 灰色系（辅助文本） -->
<style name="tv_gray_1" parent="tv_base">
    <item name="android:textColor">@color/func_gray_text_1</item>
</style>
<style name="tv_gray_2" parent="tv_base">
    <item name="android:textColor">@color/func_gray_text_2</item>
</style>

<!-- 橙色系（强调文本） -->
<style name="tv_orange_1" parent="tv_base">
    <item name="android:textColor">@color/func_orange_text_1</item>
</style>

3.3 字号层定义

<!-- 黑色主文本 + 各种字号 -->
<style name="tv_black_1_size_12" parent="tv_black_1">
    <item name="android:textSize">12sp</item>
</style>
<style name="tv_black_1_size_14" parent="tv_black_1">
    <item name="android:textSize">14sp</item>
</style>
<style name="tv_black_1_size_15" parent="tv_black_1">
    <item name="android:textSize">15sp</item>
</style>
<style name="tv_black_1_size_16" parent="tv_black_1">
    <item name="android:textSize">16sp</item>
</style>

<!-- 灰色辅助文本 + 常用字号 -->
<style name="tv_gray_2_size_12" parent="tv_gray_2">
    <item name="android:textSize">12sp</item>
</style>
<style name="tv_gray_2_size_14" parent="tv_gray_2">
    <item name="android:textSize">14sp</item>
</style>

屏幕适配优势：这种集中定义的方式还有一个重要好处——便于屏幕适配。如果有一天需要支持多尺寸屏幕，只需将硬编码的 15sp 修改为 @dimen/size_15，然后在不同的 dimens 文件中定义不同的值即可，整个改动只需要修改 tv style 这一个文件。

3.4 组合效果

颜色层	字号层	组合结果	用途
`tv_black_1`	`size_15`	`tv_black_1_size_15`	商品标题、主要内容
`tv_black_2`	`size_13`	`tv_black_2_size_13`	副标题、次要内容
`tv_gray_2`	`size_12`	`tv_gray_2_size_12`	提示文字、辅助说明
`tv_orange_1`	`size_14`	`tv_orange_1_size_14`	强调文字、按钮文字

四、按钮 Style：同样的思路，不同的属性

Button Style 是「业务绑定」的重灾区。很多中大型团队的项目里，你会看到 BtnLoginSubmit、BtnOrderPay、BtnMemberOpen 并排存在——它们往往只是胶囊主按钮的重复拷贝，圆角、字重、背景几乎一样，却无法复用、无法统一换肤、无法做全 App 主题。这是业内极其普遍的痛点；根因同样是把 业务名当成了 Style 名，而正确的命名只能落在职能上：主操作、次操作、描边强调、小尺寸等。

4.1 按钮必须的基础属性

<style name="BaseButton" parent="android:Widget.Button">
    <item name="android:textSize">15sp</item>
    <item name="android:textStyle">bold</item>
    <item name="android:letterSpacing">0.02</item>
    <item name="android:gravity">center</item>
    <item name="android:minHeight">48dp</item>
    <item name="android:paddingLeft">24dp</item>
    <item name="android:paddingRight">24dp</item>
</style>

4.2 按钮属性分析

属性	必要性	工程经验
`textSize=15sp`	必须	按钮文字需要足够大，保证可点击性
`textStyle=bold`	必须	按钮需要视觉强调，加粗效果更好
`letterSpacing=0.02`	必须	适当增加字间距提升可读性
`minHeight=48dp`	必须	符合 Material Design 规范，保证点击区域
`paddingLeft/Right=24dp`	必须	左右内边距保证文字不贴边

4.3 按钮的正交组合

<!-- 胶囊按钮 -->
<style name="Btn.Orange.Capsule.Emphasis" parent="BaseButton">
    <item name="android:background">@drawable/sel_orange_interact_capsule_emphasis_default</item>
    <item name="android:textColor">@color/func_white_text_1</item>
</style>

<style name="Btn.Gray.Capsule.Neutral" parent="BaseButton">
    <item name="android:background">@drawable/sel_gray_interact_capsule_neutral_default</item>
    <item name="android:textColor">@color/func_black_text_1</item>
</style>

<!-- 小尺寸按钮 -->
<style name="Btn.Orange.Capsule.Small" parent="BaseButton">
    <item name="android:minHeight">36dp</item>
    <item name="android:textSize">13sp</item>
    <item name="android:paddingLeft">16dp</item>
    <item name="android:paddingRight">16dp</item>
    <item name="android:background">@drawable/sel_orange_interact_capsule_emphasis_default</item>
    <item name="android:textColor">@color/func_white_text_1</item>
</style>

<!-- 描边按钮 -->
<style name="Btn.Orange.Outline.Emphasis" parent="BaseButton">
    <item name="android:background">@drawable/sel_orange_interact_outline_emphasis_default</item>
    <item name="android:textColor">@color/func_orange_text_1</item>
</style>

Btn.Orange.Capsule.Emphasis 表达的是橙色 + 胶囊形态 + 强调档位，与 Drawable sel_orange_interact_capsule_emphasis_default 同序（色系在前）；登录页、收银台、活动页主按钮都可引用，不要把业务写进 Style 名。

4.4 反例：业务型 Button Style 如何毁掉复用

❌ 错误：Style 名承载业务
Btn.Login.Submit
Btn.Order.ConfirmPay
Btn.Profile.EditSave
Btn.Cart.CheckoutNow

看似清晰，实则每个业务线各维护一套「主按钮」，设计改一版主色或圆角，要改几十个 Style、走查几十个页面。正确做法是收敛到 Btn.Orange.Capsule.Emphasis、Btn.Gray.Capsule.Neutral、Btn.Orange.Outline.Emphasis 等职能命名（色系在形状之前），与 Drawable sel_orange_interact_capsule_emphasis_default 字段顺序一致。

维度	业务命名	职能命名
回答的问题	这是哪个页面的按钮？	这是什么形态、什么强调级别的按钮？
能否跨页面复用	❌ 基本不能	✅ 全 App 复用
主题/品牌升级	改多处、易遗漏	改 Style + token 即可
典型名称	`BtnOrderPay`	`Btn.Orange.Capsule.Emphasis`

五、复用效果对比

5.1 改造前：每个 TextView 都要写完整属性

<!-- 改造前：每个都要写 4-5 行 -->
<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:includeFontPadding="false"
    android:textColor="@color/func_black_text_1"
    android:textSize="15sp"
    android:text="商品名称" />

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:includeFontPadding="false"
    android:textColor="@color/func_gray_text_2"
    android:textSize="12sp"
    android:text="库存紧张" />

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:includeFontPadding="false"
    android:textColor="@color/func_red_text_1"
    android:textSize="14sp"
    android:text="¥299" />

5.2 改造后：一行解决

<!-- 改造后：只需引用 style -->
<TextView
    style="@style/tv_black_1_size_15"
    android:text="商品名称" />

<TextView
    style="@style/tv_gray_2_size_12"
    android:text="库存紧张" />

<TextView
    style="@style/tv_red_1_size_14"
    android:text="¥299" />

5.3 量化对比

指标	改造前	改造后	节省比例
代码行数（3个TextView）	15 行	6 行	60%
属性定义次数	12 次	0 次	100%
维护点	每个 TextView	1 个 Style 文件	99%

六、命名规范：让复用更直观

6.1 文字 Style 命名

tv_{色系}_{档位}_size_{字号}

示例：

tv_black_1_size_15：黑色主文本，15sp
tv_gray_2_size_12：灰色辅助文本，12sp
tv_orange_1_size_14：橙色强调文本，14sp

6.2 按钮 Style 命名

Btn.{色系}.{形状}.{交互档位}[.Small]

示例（与 Drawable sel_{色系}_… 一致，色系紧挨 Btn 前缀）：

Btn.Orange.Capsule.Emphasis：橙色胶囊强调按钮
Btn.Gray.Capsule.Neutral：灰色胶囊中性按钮
Btn.Orange.Outline.Emphasis：橙色描边强调按钮
Btn.Orange.Capsule.Small：橙色胶囊小尺寸

6.3 命名原则

职能语义，而非业务语义：Orange / Emphasis / black_1 描述的是色系与 UI 档位，不是订单、登录、会员等业务模块
层次清晰：tv_{色系}_{档位}；Btn_{色系}_{形状}_{档位}，色系位置与颜色层、Drawable 层对齐
易于搜索：统一前缀便于 IDE 搜索；全团队共用同一套职能 Style，而不是每人发明业务名

七、与颜色体系的集成

7.1 完整数据流

7.2 主题切换支持

由于 Style 通过 @color/func_* 引用功能色，而功能色又通过 @color/t_* 引用主题色，所以：

日间：tv_black_1_size_15 → func_black_text_1 → t_black_8 → black_8
夜间：tv_black_1_size_15 → func_black_text_1 → t_black_8 → white_1（由 values-night 中 t_* 映射决定）

无需修改任何 Style，自动适配主题。

八、实际项目中的最佳实践

8.1 渐进式改造

8.2 团队协作规范

所有新增 TextView 必须使用设计师定义的 tv_* Style
禁止在布局中直接定义 textColor、textSize、includeFontPadding
需要新的颜色+字号组合时，由设计师在 styles_tv.xml 中新增，研发提需求、不自行加 token
定期审查，清理直接定义属性的代码

8.3 扩展原则

场景	做法
需要新字号	设计师在对应色系下添加（如 `tv_black_1_size_17`）
需要新色系	设计师先补功能色，再添加 `tv_purple_1` 及字号组合
需要特殊效果	优先在设计规范中沉淀；确属个例时可在布局用 `textStyle` 等覆盖

九、总结

Style 层不是简单的"属性集合"，而是工程经验的沉淀和复用。

核心价值

消除冗余：将重复属性抽取到 Style 中，写一次用无数次
统一标准：通过 tv_base 确保所有 TextView 有一致的基础行为
降低维护成本：修改一处，全局生效
支持主题切换：与颜色体系无缝集成

关键设计原则

职能 ≠ 业务：Style 只命名 UI 职能；业务场景只选择引用哪条 Style
最小化基础层：tv_base 只定义 3 个必须属性
正交组合：颜色和字号分开定义，灵活组合
按钮同样职能化：Btn.Orange.Capsule.Emphasis 等全 App 复用，禁止 BtnXxxBusiness 式命名

预期收益

根据我们的实践经验，引入 Style 层后：

代码量减少 30-50%（布局文件）
维护时间减少 80%（属性修改）
视觉一致性提升（避免手动书写错误）

参考代码（与本文配套的实现仓库一致）：

💡 如果你觉得这篇文章对你有帮助，欢迎点赞、收藏、转发。关注我，获取更多Android架构设计干货。

系列文章：

第一篇：三层颜色体系与系统化设计方案

第二篇：Drawable 层规范与工程实践

第三篇：Style 层如何系统性消除代码冗余（本文）

第四篇：设计主权回归与团队落地

Modern UI Architecture (Part 2): Drawable Layer Conventions

goodlords — Tue, 19 May 2026 05:14:02 +0000

现代化 UI 架构：Drawable 层规范与工程实践

本文是 UI 架构系列的第二篇，建议先阅读第一篇：三层颜色体系与系统化设计方案了解核心设计理念。

前言

在上一篇文章中，我们建立了一套完整的颜色体系。但颜色只是 UI 的基础，真正让 UI 活起来的是形态和交互。

一个按钮不仅需要颜色，还需要：

圆角、描边、阴影
按下、禁用、选中的状态变化
渐变、透明等视觉效果

这些都需要通过 Drawable 来实现。

贯穿 UI 架构层的一条铁律：颜色、Drawable、Style 等所有资源定义，都不要和业务挂钩；命名表达的是 UI 职能，职能 ≠ 业务。一旦用「登录页按钮」「订单失败红框」这类业务语义去命名或拆分资源，就等于把形态和颜色锁死在某个页面——可复用性会被立刻破坏。Drawable 层只描述形态、色系、交互状态与档位，业务含义由使用它的页面自己承担。

跨平台：Android 的 Drawable/selector 对应 iOS 的 Asset Catalog 状态图、Web 的 design-token + CSS 状态类；命名与分层思想一致。

本文要点：

为什么需要 Drawable 层规范
Drawable 层的三层架构设计
统一的命名规范
形态层和组件层的设计要点

一、为什么需要 Drawable 层规范？

1.1 反例：混乱的 Drawable 管理

在我接触过的项目中，经常会看到这样的 Drawable 定义：

<!-- btn_primary.xml -->
<shape>
    <solid android:color="#FF4B00" />
    <corners android:radius="24dp" />
</shape>

<!-- btn_primary_pressed.xml -->
<shape>
    <solid android:color="#CC3D00" />
    <corners android:radius="24dp" />
</shape>

<!-- btn_disabled.xml -->
<shape>
    <solid android:color="#CCCCCC" />
    <corners android:radius="24dp" />
</shape>

1.2 问题分析

问题类型	具体表现	影响
重复定义	每个状态都要单独定义一个文件	维护成本高
颜色硬编码	直接写色值，无法跟随主题切换	主题适配困难
命名混乱	`btn_primary`、`button_normal` 等命名不统一	新人难以选择
难以维护	改一个圆角需要修改所有文件	修改成本高

1.3 根本原因

这些问题的本质在于：形态定义与颜色、状态过度耦合。当一个 Drawable 文件同时承载了形状、颜色和状态逻辑时，任何改动都会变得非常困难。

二、Drawable 层的三层架构

借鉴颜色体系的设计思路，我们同样采用三层架构来管理 Drawable：

2.1 核心原则

层级	职责	特点
组件层	组合状态和形态	通过 selector 引用 bg_*，实现状态切换
形态层	定义圆角、描边、填充结构	颜色只引用 `func_*`，禁止硬编码色值
颜色层	提供颜色 token	设计师维护的功能色，支持主题切换

与业务解耦：三层都只表达「UI 语言」，不表达「业务故事」。sel_orange_interact_capsule_emphasis_default 可以在下单主按钮、会员开通按钮、活动页主按钮上复用；若做成 sel_order_submit_primary，换页面就要复制一套 Drawable，主题与形态也无法在全 App 统一维护。

三、命名规范：让每个文件都有明确的含义

3.1 命名公式

{类型}_{色系}_{用途}_{状态}_{档位}

3.2 组成说明

组成部分	说明	允许值
类型	Drawable 类别	`bg`（背景）、`sel`（选择器）、`ic`（图标）
色系	颜色分类	`gray`、`orange`、`red`、`blue`、`green`、`black`、`white`
用途	使用场景	`surface`、`fill`、`stroke`、`field`、`interact`、`gradient`
状态	交互状态	`idle`、`alert`、`hint`、`emphasis`、`neutral`、`default`
档位	优先级	数字 `1`（主要）、`2`（次要）、`3`（第三）

3.3 命名示例

bg_orange_fill_interact_1    // 橙色交互填充背景，主档位
bg_gray_surface_card_1       // 灰色卡片表面背景
sel_orange_interact_outline_emphasis_default  // 橙色描边交互选择器
bg_black_fill_scrim_1        // 黑色遮罩填充

3.4 反例：业务绑定如何毁掉复用

❌ 错误：文件名承载业务，无法跨场景复用
bg_login_page_primary_btn.xml
bg_order_detail_pay_btn.xml
sel_profile_avatar_upload_error.xml

三个文件往往只是圆角、色值、状态略有相似，却无法合并维护。正确做法是共用 sel_orange_interact_capsule_emphasis_default 等职能 + 形态命名，由不同页面的布局或 Style 决定用在哪里。

四、形态层设计：结构 + 功能色引用

4.1 基础形状类型

形状	用途	示例
fill	实心填充	按钮背景、卡片背景
stroke	描边空心	输入框边框、幽灵按钮
flat	扁平透明	文字按钮、点击区域
gradient	渐变效果	渐变背景、光晕效果
surface	表面效果	卡片、浮层、阴影

4.2 形状定义规范

<!-- bg_orange_fill_interact_1.xml -->
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <solid android:color="@color/func_orange_bg_1" />
    <corners android:radius="@dimen/draw_corner_capsule" />
</shape>

<!-- bg_orange_stroke_interact_1.xml -->
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <solid android:color="@color/func_clear_1" />  <!-- 透明填充 -->
    <stroke 
        android:width="@dimen/draw_stroke_reg" 
        android:color="@color/func_orange_border_1" />
    <corners android:radius="@dimen/draw_corner_capsule" />
</shape>

关键设计点：

使用 @dimen 引用尺寸（由设计师在 dimens 中定义），避免硬编码
使用 @color/func_* 引用功能色，支持主题切换；禁止在 drawable 中写 #RRGGBB 或直接引用 t_*、基础色
同一套圆角/描边结构可搭配不同色系的功能色，由设计师在 token 层切换映射

五、状态色设计：状态逻辑放在 Drawable 层

在设计这套体系时，我们曾讨论过是否需要添加「禁用态」「选中态」「按下态」等状态相关的颜色到颜色层。

结论：状态色应该放在 drawable 层，而不是颜色层。

状态类型	建议位置	原因
禁用态	drawable层	通过selector组合实现
选中态	drawable层	通过selector组合实现
按下态	drawable层	通过selector组合实现

5.1 为什么不在颜色层定义状态色？

职责分离：颜色层负责提供「原料」，drawable层负责组合「成品」
灵活性：同一个颜色可以在不同状态下有不同表现
可复用性：一套颜色可以组合出多种状态效果

5.2 状态效果的正确实现方式

<!-- drawable/sel_orange_interact_capsule_emphasis_default.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 禁用态 -->
    <item android:state_enabled="false">
        <shape>
            <solid android:color="@color/func_black_bg_2" />  <!-- 禁用态用灰色背景 -->
            <corners android:radius="24dp" />
        </shape>
    </item>
    <!-- 按下态 -->
    <item android:state_pressed="true">
        <shape>
            <solid android:color="@color/func_orange_bg_2" />  <!-- 按下态用浅色 -->
            <corners android:radius="24dp" />
        </shape>
    </item>
    <!-- 常态 -->
    <item>
        <shape>
            <solid android:color="@color/func_orange_bg_1" />  <!-- 常态用主色 -->
            <corners android:radius="24dp" />
        </shape>
    </item>
</selector>

六、组件层设计：状态组合

6.1 Selector 的规范写法

<!-- sel_orange_interact_capsule_emphasis_default.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 禁用态 -->
    <item 
        android:drawable="@drawable/bg_gray_fill_interact_2" 
        android:state_enabled="false" />
    <!-- 按下态 -->
    <item 
        android:drawable="@drawable/bg_orange_fill_interact_2" 
        android:state_pressed="true" />
    <!-- 常态 -->
    <item android:drawable="@drawable/bg_orange_fill_interact_1" />
</selector>

6.2 状态优先级

Selector 中状态判断优先级（高 → 低）：禁用态 > 选中态 > 按下态 > 焦点态 > 常态

6.3 输入框状态示例

<!-- sel_gray_field_rect_idle_default.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item 
        android:drawable="@drawable/bg_gray_field_rect_2" 
        android:state_enabled="false" />
    <item 
        android:drawable="@drawable/bg_blue_field_rect_1" 
        android:state_focused="true" />
    <item android:drawable="@drawable/bg_gray_field_rect_1" />
</selector>

七、常用组件的 Drawable 实现

7.1 按钮组件

按钮类型	Drawable 配置
主按钮	`sel_orange_interact_capsule_emphasis_default`
次按钮	`sel_gray_interact_capsule_neutral_default`
文字按钮	`sel_gray_interact_flat_neutral_default`
幽灵按钮	`sel_orange_interact_outline_emphasis_default`

7.2 输入框组件

状态	Drawable 配置
常态	`sel_gray_field_rect_idle_default`
警告态	`sel_yellow_field_rect_hint_static`
错误态	`sel_red_field_rect_alert_static`

7.3 卡片组件

卡片类型	Drawable 配置
普通卡片	`bg_gray_surface_card_1`
浮层卡片	`bg_gray_surface_float_1`
面板卡片	`bg_gray_surface_panel_1`

八、尺寸管理：统一的 Dimen 规范

8.1 圆角尺寸

<!-- dimens_drawable.xml -->
<dimen name="draw_corner_none">0dp</dimen>
<dimen name="draw_corner_sm">4dp</dimen>
<dimen name="draw_corner_reg">8dp</dimen>
<dimen name="draw_corner_lg">12dp</dimen>
<dimen name="draw_corner_capsule">999dp</dimen>  <!-- 胶囊形 -->

8.2 描边尺寸

<dimen name="draw_stroke_thin">0.5dp</dimen>
<dimen name="draw_stroke_reg">1dp</dimen>
<dimen name="draw_stroke_thick">2dp</dimen>

8.3 阴影尺寸

<dimen name="draw_shadow_elevation_1">2dp</dimen>
<dimen name="draw_shadow_elevation_2">4dp</dimen>
<dimen name="draw_shadow_elevation_3">8dp</dimen>

九、与颜色体系的集成

9.1 颜色引用规范

<!-- ✅ 正确：引用功能色层 -->
<solid android:color="@color/func_orange_bg_1" />
<stroke android:color="@color/func_orange_border_1" />

<!-- ❌ 错误：直接引用主题色或基础色 -->
<solid android:color="@color/t_orange_4" />  <!-- 不推荐 -->
<solid android:color="@color/orange_4" />    <!-- 禁止 -->

9.2 夜间模式自动适配

得益于三层颜色架构，Drawable 层无需任何修改即可支持夜间模式：

日间模式：
func_orange_bg_1 → t_orange_4 → orange_4 (#FF4B00)

夜间模式：
func_orange_bg_1 → t_orange_4 → orange_3b (#FF8833)

十、与 View 的集成方式

10.1 通过 Style 引用

<!-- styles_button.xml -->
<style name="Btn.Orange.Capsule.Emphasis" parent="BaseButton">
    <item name="android:background">@drawable/sel_orange_interact_capsule_emphasis_default</item>
    <item name="android:textColor">@color/func_white_text_1</item>
</style>

10.2 在布局中直接使用

<Button
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@drawable/sel_orange_interact_capsule_emphasis_default"
    android:text="主操作" />

十一、完整架构总结

十二、总结

Drawable 层是连接颜色和 UI 组件的桥梁，它的设计直接影响到：

UI 的一致性和美观度
代码的可维护性
主题切换的灵活性

通过遵循以下原则，你可以构建一套优秀的 Drawable 体系：

与业务解耦：Drawable 只表达形态与交互语义，绝不使用页面名、流程名、业务事件名
分离关注点：形态结构与填色引用分离，状态组合与组件分离
统一命名规范：{类型}_{色系}_{用途}_{状态}_{档位}
复用优先：避免重复定义，提高资源利用率
与颜色体系集成：只引用设计师定义的 func_*，支持主题切换

参考代码：

💡 如果你觉得这篇文章对你有帮助，欢迎点赞、收藏、转发。关注我，获取更多 Android 架构设计干货。

系列文章：

第一篇：三层颜色体系与系统化设计方案

第二篇：Drawable 层规范与工程实践（本文）

第三篇：Style 层如何系统性消除代码冗余

第四篇：设计主权回归与团队落地

Modern UI Architecture (Part 1): Three-Layer Color System

goodlords — Tue, 19 May 2026 05:11:02 +0000

现代化 UI 架构：三层颜色体系与系统化设计方案

本文是 UI 架构系列 的第一篇，将深入探讨颜色层的设计。后续文章将依次介绍：

第二篇：Drawable 层规范与工程实践

第三篇：Style 层如何系统性消除代码冗余

第四篇：设计主权回归与团队落地

注：本文以 Android 为例进行说明，但核心思想完全适用于 iOS、React、H5、小程序等任何平台。

前言

在多年的跨平台 App 开发实践中，我发现 UI 资源管理是困扰许多团队的共性问题：

颜色定义混乱，同一个色值重复定义几十次
组件形态与颜色过度耦合，难以复用
样式属性重复书写，维护成本极高
主题切换困难，夜间模式适配工作量巨大
新同事需要花费大量时间理解混乱的颜色命名

如果你也被这些问题困扰，这个系列或许值得一读——主要面向设计总监、设计师、研发总监与前端工程师。

本文要点：

三层颜色架构的设计理念和核心原则
每一层的具体设计规范和代码实现
如何实现日间/夜间模式的无缝切换
架构的适用场景和扩展方向

架构全景

本系列介绍的是一套完整的 UI 架构体系，其中三层颜色架构是核心基础：

箭头表示引用/依赖方向：应用层引用 func_；func_* 引用 t_；t_ 引用基础色。定义权在设计侧，自下而上配置。*

颜色层依赖关系：func_* → t_* → 基础色（严格单向依赖）

本文聚焦于三层颜色架构的完整设计，后续文章将介绍上层应用层如何基于颜色层构建。

一、传统颜色管理的核心痛点

1.1 真实项目中的反例

在我接触过的多个项目中，经常会看到类似这样的颜色定义：

<!-- 从真实项目中截取的颜色定义 -->
<color name="bg_login">#FFFFFF</color>      <!-- 登录页背景 -->
<color name="bg_home">#F5F5F5</color>      <!-- 首页背景 -->
<color name="bg_profile">#FFFFFF</color>    <!-- 个人中心背景 -->
<color name="text_title">#141414</color>   <!-- 标题文字 -->
<color name="text_desc">#808080</color>    <!-- 描述文字 -->
<color name="text_hint">#BFBFBF</color>    <!-- 提示文字 -->
<color name="button_red">#DB121F</color>   <!-- 红色按钮 -->
<color name="red_button">#DB121F</color>   <!-- 另一个红色按钮 -->

1.2 问题分析

问题类型	具体表现	影响
重复定义	`#FFFFFF` 和 `#DB121F` 多次出现	改一处需改所有地方，容易遗漏
业务绑定	`bg_login`、`bg_home` 与具体页面绑定	无法复用，扩展性差
命名混乱	`button_red` 和 `red_button` 同时存在	新人难以选择，团队协作困难
夜间模式灾难	需复制所有颜色到 `values-night`	工作量巨大，容易出错

1.3 根本原因

这些问题的本质在于：颜色定义与业务语义、主题逻辑过度耦合。当一个颜色既承载了"背景"的业务含义，又承载了"白色"的具体色值时，任何改动都会牵一发而动全身。

二、三层颜色架构设计理念

针对这些问题，我设计了一套严格单向依赖的三层颜色架构：

2.1 架构核心原则

层级	唯一职责	命名规则	是否承载业务语义	修改频率
基础色层	定义原始色值	`色系_数字`（如 `white_1`）	❌ 否	极低（品牌升级时才改）
主题层	日间/夜间模式映射	`t_色系_数字`（如 `t_white_1`）	❌ 否	低（新增主题时才改）
功能色层	UI 职能封装（文本、背景、边框等）	`func_{色系}_{职能}_{档位}`（如 `func_black_text_1`）	❌ 否	由设计师维护（新增档位/职能时改）

重要说明：功能色层封装的是 UI 职能（如文本、背景、边框），而非具体业务场景。func_black_text_1 代表黑色系主档文本色，可用于商品标题、页面标题、按钮文字等任何场景，不绑定具体业务。功能色的定义权归属设计师，研发只引用、不新增。

2.2 严格单向依赖规则

为什么必须严格遵守单向依赖？

避免循环依赖导致的颜色定义混乱
每层只做自己的事，职责清晰，便于定位问题
改一处全局生效，维护成本极低
多人开发不会互相冲突

三、分层详解：每一层该怎么设计

3.1 第一层：全局基础色层

定位：纯原始色值定义，不做任何主题绑定和业务关联

命名规则：色系_数字 下划线格式，数字按明度/饱和度递增

设计原则：

白色系：数字越小越浅（white_1 = 纯白）
黑色系：数字越小越浅（black_1 = 浅灰）
彩色系：数字越小饱和度越低
不参与日夜切换，保持绝对稳定

完整基础色表（与仓库实现一致）：

色系	档位数	命名区间 / 说明
白色系	4	`white_1` ~ `white_4`
黑色系	8	`black_1` ~ `black_8`
灰色系	7	`gray_1` ~ `gray_7`
红色系	4	`red_1` ~ `red_4`
橙色系	4	`orange_1` ~ `orange_4`；含 `orange_0`、`orange_2b`、`orange_3b`
黄色系	4	`yellow_1` ~ `yellow_4`
蓝色系	4	`blue_1` ~ `blue_4`
绿色系	4	`green_1` ~ `green_4`
补间色	按需	如 `black_5a`
透明度变体	按需	`基础色名_alpha{透明度}`

代码示例：

<!-- ✅ 正确：统一色系_数字命名 -->
<color name="white_1">#FFFFFF</color>
<color name="black_8">#000000</color>
<color name="red_4">#DB121F</color>
<color name="black_1">#F0F0F0</color>
<color name="white_1_alpha20">#33FFFFFF</color>

3.2 第二层：主题适配层（t_）

定位：唯一的日夜模式映射层，只做色值代理，不承载任何业务语义

命名规则：t_基础色名，与基础色一一对应

设计原则：

只引用基础色层变量，绝对不写具体色值
日间/夜间模式通过 Android 资源限定符自动切换
保持与基础色完全一致的命名，便于维护

错误做法（常见误区）：

<!-- ❌ 错误：主题层承载了业务语义 -->
<!-- values/colors.xml -->
<color name="t_bg_page">#FFFFFF</color>
<color name="t_text_main">#000000</color>

<!-- values-night/colors.xml -->
<color name="t_bg_page">#141414</color>
<color name="t_text_main">#FFFFFF</color>

问题：主题层承载了业务语义，破坏了分层原则。新增主题时需要复制所有业务语义的颜色。

正确做法：

<!-- ✅ 正确：只做颜色映射，不关心用途 -->
<!-- values/colors_theme_tokens.xml（日间模式） -->
<color name="t_white_1">@color/white_1</color>
<color name="t_black_8">@color/black_8</color>
<color name="t_orange_4">@color/orange_4</color>

<!-- values-night/colors_theme_tokens.xml（夜间模式） -->
<color name="t_white_1">@color/black_8</color>   <!-- 背景色反转 -->
<color name="t_black_8">@color/white_1</color>   <!-- 主文字色反转 -->
<color name="t_orange_4">@color/orange_3b</color> <!-- 夜间使用较浅的橙色 -->

优势：

主题层只做颜色映射，不关心用途
新增主题只需要加一个资源目录
夜间模式切换完全由 Android 系统自动处理，零代码侵入

3.3 第三层：功能色层（func_）

定位：面向 UI 职能的语义抽象层，不承载业务语义（如「登录页背景」「删除按钮红」）

命名规则：func_{色系}_{职能}_{档位}，档位数字按该职能下的深浅/重要性递增

设计原则：

只引用主题层变量，绝对不直接引用基础色
采用「色系 × 职能 × 数字档位」模式，保留无限扩展能力
由设计师在资源文件中定义与维护；研发在布局/代码中只引用已有 token

为什么我反对固定语义命名？

很多人喜欢这样定义功能色：

<color name="func_text_main">@color/t_black_8</color>
<color name="func_text_sub">@color/t_black_5</color>
<color name="func_text_aux">@color/t_black_3</color>

这在实际项目中会出问题：中间态越来越多，命名很快失控。比如需要一个介于 sub 和 aux 之间的颜色时，该叫 func_text_sub2 还是 func_text_medium？

最佳实践：色系 + 职能 + 数字档位

<!-- 黑色系文本：档位越小越深、越重要 -->
<color name="func_black_text_1">@color/t_black_8</color>
<color name="func_black_text_2">@color/t_black_7</color>
<color name="func_black_text_3">@color/t_black_5</color>
<color name="func_black_text_4">@color/t_black_3</color>

<!-- 黑色系背景：档位越小越浅 -->
<color name="func_black_bg_1">@color/t_black_8</color>
<color name="func_black_bg_2">@color/t_black_7</color>

<!-- 橙色系强调 -->
<color name="func_orange_text_1">@color/t_orange_4</color>
<color name="func_orange_bg_1">@color/t_orange_4</color>

无限扩展能力：

需要在 func_black_text_2 与 func_black_text_3 之间加一档，由设计师新增 func_black_text_25 即可
不用造 func_product_title 这类业务名
规范可长期稳定

职能分类速览（详见第六节完整矩阵）：

职能后缀	命名示例	典型用途
`_text`	`func_black_text_1`	各级文字
`_bg`	`func_gray_bg_1`	页面、卡片背景
`_border`	`func_gray_border_1`	边框
`_divider`	`func_black_divider_1`	分割线
`_alpha`	`func_black_alpha_1`	遮罩、半透明
`_shadow`	`func_black_shadow_1`	阴影

四、两个关键争议点的深度解析

4.1 争议1：主题层到底该不该承载业务语义？

我的答案：绝对不应该。

主题层的本质是颜色代理，它的唯一职责是根据当前主题返回对应的基础色。它不应该关心这个颜色是用来做背景还是文字。

如果主题层承载了业务语义：

每新增一个主题，你都要复制所有业务语义的颜色
业务语义变化时，你需要修改所有主题文件
架构的解耦性被完全破坏

4.2 争议2：功能层用数字命名会不会可读性差？

不会，只要约定好规则。

我们只需要在团队内部约定：

文本色：数字越小越重要、越深
背景色：数字越小越浅
边框色：数字越小越深

新人只需要花 5 分钟就能记住这些规则，比记住几十个不同的语义名称要容易得多。

五、核心优势：为什么这套架构能解决问题？

5.1 维护成本显著降低

改色流程对比：

操作	传统做法	三层架构
改品牌色	全局搜索替换几百个地方	修改基础色层一处
适配夜间模式	修改所有颜色定义	自动切换，零代码
新增页面	定义 5-10 个新颜色	复用设计师已定义的功能色

5.2 无限扩展能力

新增色系：只需要在基础色层添加
新增主题：只需要加一个资源目录
新增 UI 职能档位：由设计师在功能层顺延数字编号

5.3 团队协作零成本

统一的命名规范，没有歧义
新成员 5 分钟就能上手
多人开发不会互相冲突

六、功能色层详解：7大色系 × 6种职能

在实际项目中，我们发现一个 App 中常用的颜色职能只需要6种：

职能	用途	示例
文本色	文字显示	标题、正文、辅助文字
背景色	填充区域	页面背景、卡片背景
边框色	勾勒边界	输入框边框、卡片边框
分割线	分隔内容	列表分割线、区域分隔
透明度	半透明效果	遮罩、玻璃效果
阴影色	阴影效果	卡片阴影、按钮阴影

而这 6 种职能，组合7大色系，就构成了一个完整的颜色体系。

6.1 为什么是这7大色系？

色系	特点	主要用途
黑色系	从纯黑到浅灰的完整灰阶	正文、次要文字、背景
灰色系	独立的灰色梯度	辅助信息、禁用状态
红色系	高饱和度警示色	错误、删除、警告
黄色系	温和警示色	待处理、进行中
橙色系	强调色	热销、促销、主按钮
蓝色系	信任色	链接、信息、成功
绿色系	正向色	成功、增长、完成

6.2 完整颜色矩阵

文本色（7色系 × 4档 = 28个）：

色系	命名	深浅/饱和度
黑色系	`func_black_text_1` ~ `func_black_text_4`	1最深 → 4最浅
灰色系	`func_gray_text_1` ~ `func_gray_text_4`	1最深 → 4最浅
红色系	`func_red_text_1` ~ `func_red_text_4`	1高饱和 → 4低饱和
黄色系	`func_yellow_text_1` ~ `func_yellow_text_4`	1高饱和 → 4低饱和
橙色系	`func_orange_text_1` ~ `func_orange_text_4`	1高饱和 → 4低饱和
蓝色系	`func_blue_text_1` ~ `func_blue_text_4`	1高饱和 → 4低饱和
绿色系	`func_green_text_1` ~ `func_green_text_4`	1高饱和 → 4低饱和

背景色（7色系 × 2档 = 14个）：

色系	命名	用途
黑色系	`func_black_bg_1`, `func_black_bg_2`	深色背景
灰色系	`func_gray_bg_1`, `func_gray_bg_2`	浅灰背景、卡片
红色系	`func_red_bg_1`, `func_red_bg_2`	错误背景
黄色系	`func_yellow_bg_1`, `func_yellow_bg_2`	警告背景
橙色系	`func_orange_bg_1`, `func_orange_bg_2`	强调背景
蓝色系	`func_blue_bg_1`, `func_blue_bg_2`	信息背景
绿色系	`func_green_bg_1`, `func_green_bg_2`	成功背景

边框色（7色系 × 2档 = 14个）：

色系	命名	用途
黑色系	`func_black_border_1`, `func_black_border_2`	常规边框
灰色系	`func_gray_border_1`, `func_gray_border_2`	辅助边框
红色系	`func_red_border_1`, `func_red_border_2`	错误边框
黄色系	`func_yellow_border_1`, `func_yellow_border_2`	警告边框
橙色系	`func_orange_border_1`, `func_orange_border_2`	强调边框
蓝色系	`func_blue_border_1`, `func_blue_border_2`	信息边框
绿色系	`func_green_border_1`, `func_green_border_2`	成功边框

分割线、透明度、阴影色（各7色系 × 2档 = 各14个）：

色系	分割线命名	透明度命名	阴影命名
黑色系	`func_black_divider_1~2`	`func_black_alpha_1~2`	`func_black_shadow_1~2`
灰色系	`func_gray_divider_1~2`	`func_gray_alpha_1~2`	`func_gray_shadow_1~2`
红色系	`func_red_divider_1~2`	`func_red_alpha_1~2`	`func_red_shadow_1~2`
黄色系	`func_yellow_divider_1~2`	`func_yellow_alpha_1~2`	`func_yellow_shadow_1~2`
橙色系	`func_orange_divider_1~2`	`func_orange_alpha_1~2`	`func_orange_shadow_1~2`
蓝色系	`func_blue_divider_1~2`	`func_blue_alpha_1~2`	`func_blue_shadow_1~2`
绿色系	`func_green_divider_1~2`	`func_green_alpha_1~2`	`func_green_shadow_1~2`

理论矩阵规模：7 色系 × 6 职能 × 2–4 档 ≈ 84 个 token，可覆盖绝大多数通用 UI 场景。本仓库 demo 仅实现常用子集（见 colors_semantic.xml）；完整矩阵由设计师按产品需要逐步补齐，研发不自行「补色」。

6.3 核心原则：职能无关，业务通用

这套颜色体系是业务无关的。同一个 func_red_text_1：

在电商 App 中可以用作「商品下架」提示
在社交 App 中可以用作「被拉黑」提示
在金融 App 中可以用作「交易失败」提示

颜色本身不承载业务语义，业务语义由使用场景决定。

6.4 反例 vs 正例

反例：业务绑定

<!-- ❌ 错误：业务绑定，无法复用 -->
<color name="func_product_delete_text">@color/t_red_5</color>    <!-- 商品删除文字 -->
<color name="func_order_cancel_text">@color/t_red_5</color>    <!-- 订单取消文字 -->

正例：职能无关

<!-- ✅ 正确：职能无关，业务通用 -->
<color name="func_red_text_1">@color/t_red_5</color>    <!-- 任何需要红色文字的地方 -->
<color name="func_red_text_2">@color/t_red_4</color>    <!-- 任何需要浅红文字的地方 -->

6.5 完整命名规范速查表

命名公式：func_{色系}_{职能}_{档位}

色系前缀：

前缀	色系	示例
`black`	黑色系	`func_black_text_1`
`gray`	灰色系	`func_gray_text_1`
`red`	红色系	`func_red_text_1`
`yellow`	黄色系	`func_yellow_text_1`
`orange`	橙色系	`func_orange_text_1`
`blue`	蓝色系	`func_blue_text_1`
`green`	绿色系	`func_green_text_1`

职能后缀：

后缀	职能	档位
`_text`	文本色	1-4档
`_bg`	背景色	1-2档
`_border`	边框色	1-2档
`_divider`	分割线	1-2档
`_alpha`	透明度	1-2档
`_shadow`	阴影色	1-2档

七、总结

这套三层颜色架构的核心思想其实很简单：解耦。

把色值定义和主题适配解耦
把主题适配和 UI 职能语义解耦（职能语义仍由设计师定义，不绑定具体业务页面）
每一层只做自己最擅长的事

通过「7大色系 × 6种职能」的设计，我们构建了一套完整、可扩展、业务无关的颜色体系，覆盖 App 所有通用 UI 场景。

参考代码：

💡 如果你觉得这篇文章对你有帮助，欢迎点赞、收藏、转发。关注我，获取更多 Android 架构设计干货。