DESIGN_PHILOSOPHY.md

Karesansui Architecture

A design philosophy for Git ID Switcher

Note: Karesansui (枯山水) is a Japanese rock garden--sand and stone representing mountains and water. This philosophy is not efficiency-driven minimalism. It invests deeply in what appears simple.

---

Placing Stones

The gardener asks:

"Why is this stone here?"

A stone that cannot answer should not be placed.

This garden called Git ID Switcher faces the same question.

---

The Core

"Who am I?" — that's what we switch.

Nothing more.

git config user.name
git config user.email

It could be written in 100 lines.

That's precisely why we can spend everything else on how to place it.

---

The Stone

Immovable. The center of the garden.

Create a profile. Select it. Write to git config.

This is the stone. Everything else exists to make this stone shine.

---

Sand Patterns

Ripples raked around the stone.

Not the stone itself, but what makes the stone a stone.

90% test coverage. Structured logging. Timeout handling. Input validation.

Sand patterns go unnoticed. But a garden without them is just barren land.

---

Accents

Small presences that give the garden its story.

26 language support. Icons. SSH/GPG key association.

The garden could exist without them. But with accents, the garden becomes someone's garden.

---

Stones We Don't Place

The most important decision is what not to place.

GitHub API integration. Token management. Authentication wizards.

They might be convenient. But the moment you place them, it becomes a different garden.

The essence of karesansui lies in empty space.

---

On Over-Engineering

"That's excessive," they say.

They're right.

But no one questions ROI in a hobby garden.

Lining up coverage badges is like hanging a scroll. They're there because they're beautiful.

---

What This Is Not

Karesansui is not Western minimalism.

Western minimalism asks: "What can we remove?" Karesansui asks: "What deserves to remain?"

Western minimalism removes to save cost and effort. Karesansui invests enormously to appear simple.

In a real karesansui, sand patterns require daily raking. In this codebase, "invisible quality" requires continuous investment. The "empty" space is the most intentional part. What looks effortless demands the most effort.

"Eliminate waste" misses the point entirely. "If it works, it's fine" has no place here. In this garden, sand patterns and accents are the richness--not waste to be cut.

The goal is not efficiency or quick results. The goal is depth disguised as simplicity.

Karesansui is intentional richness that appears minimal.

---

The Practice

Why tend a garden no one visits?

Some find stillness in sitting quietly. Others find it in the act of doing--focused, unhurried, absorbed.

This is called samu: work as meditation. Not work to achieve a result. Work that needs no result.

The gardener does not strain to create perfection. The gardener tends. Returns. Tends again.

Raking sand is not about the pattern left behind. Tomorrow, the pattern will need raking again. This is not futility. This is the point.

Tests are not written to reach a number. Documentation is not crafted for readers. The maintaining is the practice.

There is no finish line. There is no applause to seek.

The act of tending--quiet, steady, here-- is itself the reward.

---

Origin

2003. CSS Zen Garden.

The same HTML held infinite styles.

Freedom exists within constraints.

What I learned in that garden became the seed of this one.

---

Coda

Git ID Switcher is art wearing the mask of open source.

To users, it functions as a tool. To the maker, it exists as a garden.

Both are true. Both are real.

And so the gardener is satisfied.

---

Badge

If you resonate with this philosophy, feel free to use one of these badges in your project:

Stone (🪨)

Preview	Markdown
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)

Zen (🧘)

Preview	Markdown
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)

Waves (🌊)

Preview	Markdown
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)
	[](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md)