Design System

[janishorsts]

Vision and Principles

EarthBuild's mission is to provide foundational technology that fundamentally changes how developers and organizations approach their workflows, while also addressing emerging concerns such as environmental impact. EarthBuild is an open-source, community-driven successor to the Earthfile project by @earthly. It is designed to be the "go-to" declarative tool for build automation, serving as a single source of truth for all build logic.

Our primary goal is to improve the Developer Experience across Software Development Processes by simplifying the lives of developers and DevOps engineers. We achieve this by eliminating the need for complex, indeterministic, environment-specific scripting and replacing it with a portable, reproducible, and highly efficient build system.

The re-branding to EarthBuild is a step to a new beginning for a project fully owned and guided by its community and contributors.

Our Guiding Principles

Our brand identity is built on four core principles that guide every aspect of the project's development and communication.

Accelerated Value delivery

The ultimate goal of our work is to enable teams to deliver value to their users faster. We remove bottlenecks in Software Development Processes by creating a build system that is reliable, fast, and simple to use, allowing developers to focus on building features and shipping them with confidence.

Determinism

Every action, every build, and every output must be reproducible. This ensures that a build "always produces the same output" given the same inputs, which is the central promise of the tool.

Simplicity

The tool is easy to learn and use. The declarative syntax of the Earthfile is a direct manifestation of this principle, prioritizing readability and ease of maintenance over complexity.

Sustainability

This is the ethical pillar of our project. The project champions and advocates for the reduction of the carbon footprint in Software Development Processes.

How We Compare to Alternatives

Feature / Value	EarthBuild	Dagger.io	Docker Bake
Core Value	Ease of Use / Accelerated Value Delivery	Build Programmability	Orchestrating Docker Image Builds
Practical Application	Serves as a single source of truth for all build logic, replacing flaky scripts and ensuring consistent builds on both local machines and CI/CD pipelines.	Used to define and run CI/CD workflows and dev environments using popular programming languages.	Orchestrates and automates complex multi-image and multi-platform Docker builds using a single declarative file.
Primary Syntax	Declarative (Earthfile)	Imperative (Programming language)	Declarative (HCL, JSON, YAML)
Underlying Engine	Custom BuildKit	Custom BuildKit	BuildKit (via docker buildx)
Core Differentiator	Simplicity & Speed	AI Integration & Multi-language SDKs	Native Docker Integration
Parallelism	Implicit (automatically determines which steps can run in parallel)	Explicit (requires manual function chaining)	Implicit: (automatically parallelizes builds)
What's not supported		Parallelism is not natively supported and requires manual function chaining

Content Guidelines

How We Talk About EarthBuild

The project's narrative is a cohesive story that links user pain points directly to EarthBuild’s unique benefits. The core message is consistent across all channels, from the website to the CLI output.

• Pain Point-to-Benefit Mapping: Our messaging addresses common frustrations:

  • "It works on my machine" is solved by EarthBuild's deterministic nature, transforming the problem into a benefit: "It works everywhere consistently.".

  • The frustration of "automation scripting spaghetti" is overcome by EarthBuild's declarative syntax, which provides "Effortless efficiency with a purpose-built language." based on familiar Dockerfile syntax.

  • The burden of "Slow, flaky CI" is addressed by the tool's advanced caching and parallelism, resulting in "Instant, reliable workflows that save time and energy.".

• The Sustainability Narrative: The "green computing" imperative is used where possible. The language is explicit, using phrases like "greener working practices" and "reduce your compute energy". The technical benefits of EarthBuild's memoization lead to an ethical benefit that transforms a technical feature into a compelling, value-driven story.

• The C-Suite Narrative: The technical benefits of EarthBuild directly translate into business value that resonates with CXOs and other senior leadership. These leaders are focused on cost, risk, and competitive advantage. Our narrative for them is built on these values:

  • Reduced Operational Costs: The tool's ability to make builds "up to a few hundred times faster" and "instant" when no changes have occurred directly reduces infrastructure spend. This is a tangible return on investment that can be measured and reported.  

  • Mitigated Operational Risk: By enforcing determinism and providing a "single source of truth" for builds, EarthBuild leads to more reliable deployments and less time spent on firefighting and debugging.  

  • Increased Developer Productivity: EarthBuild's Developer Experience, with a simple syntax and fast feedback loops, increases engineering velocity, confidence and happiness. Developers spend less time managing complex pipelines and more time building new features, accelerating time-to-market.

  • A Strategic Advantage: The explicit commitment to "greener working practices" and "saving energy" allows companies to meet their corporate social responsibility (CSR) goals and strengthens their ESG (Environmental, Social, and Governance) credentials.

How EarthBuild Improves Software Development Processes

EarthBuild's impact is seen across the entire software development lifecycle, from the initial commit to the final deployment.

• Local Development

  • EarthBuild runs tasks in containers on a developer's machine, providing a consistent environment that mimics the CI server. This allows developers to test and debug builds locally, eliminating the "it works on my machine" problem before code is even committed.

• CI/CD

  • The tool's deterministic nature, coupled with advanced BuildKit caching and implicit parallelism, makes CI pipelines drastically faster and more reliable. Builds can be "up to a few hundred times faster" and when no changes are made, the output is "instant" due to the advanced caching. This higher throughput means faster feedback loops for developers and a more efficient use of CI resources. Also, it ensures "instant deployments in CD" and eliminates production issues caused by inconsistent build processes.

• Maintenance and Security

  • EarthBuild provides a robust solution for secrets management, ensuring sensitive information is not exposed in plaintext logs or caching layers. The declarative syntax simplifies the maintenance of complex CI/CD logic across a project or an entire organization.  

Style Guideline 🚧

The project’s visual and textual identity is consistent across all platforms:

• website
• documentation (GitBook)
• LinkedIn
• Chat platform(TBC)
• CLI

The recommended principle for our user-facing designs is Material Design 3 (M3). This framework provides a robust, user-centric approach to visual design and interaction.

The style and visuals should adapt to the theme preferred by users – light or dark – on all platforms.

Web Design 🚧

The website is the primary entry point for new users and is designed with a clear user journey in mind, sparking curiosity to try and learn more about EarthBuild.

Home Page

• Hero
• Carbon Footprint Counter
• Core Values
  • Sustainability
  • Simplicity
  • Determinism
  • Community
• CTA to Try Now
• Impact on Software Development Processes
• Testimonials
• Footer

Blogs Page

[kmannislands]

I'd suggest either a natively dark theme or support for dark theme 😄

[janishorsts]

We'll support both light and dark themes.