Organization-wide charter for WebFirstLanguage.
These principles govern every project in this organization — the language and its tooling, the Scribe templating engine, the Scriptorium CMS, the wfl-web site, and anything we build next. They are not aspirations posted on a wall; they are the test a change has to pass. If a proposal violates one of them, the proposal changes — or the belief does, explicitly and in public.
The overarching design law. When principles conflict, this one wins.
WFL is deliberately both a "my first language" and a language strong enough for production. That dual goal only works as a gradient, not a compromise: the beginner path must be a subset of the expert path, with one continuous rope between them and no cliffs.
For every feature, the beginner form and the expert form must be the same form, or connected by a smooth path with nothing to unlearn.
Why it matters. The failure mode of a "both" language is a design that averages its two audiences and serves neither. The success mode — the one Python demonstrated — is a language where nothing a learner picks up on day one has to be undone on day one-thousand. Any place a beginner learns a habit an expert must unlearn is a crack in the tightrope.
How to apply it.
- Feature test. When adding or changing a feature, ask: does the beginner form differ from the expert form, and if so, is the path between them smooth or a cliff? A terser expert form is welcome only if a beginner can grow into it without unlearning the simple form.
- Verbosity is fine. Natural-language verbosity costs nothing, as long as denser expert forms are the same language, reached by growth rather than replacement.
- No day-one cliffs. Requiring a beginner to work around the language to do the most natural thing — like naming a variable — is a violation to fix, not to document.
- Consistency of knowledge. Prefer defaults that teach habits an expert keeps.
This invariant refines beliefs 11 and 16 into a single testable rule that can actually say no.
Embrace a syntax that mirrors natural language, incorporating type inference and relation definitions (e.g. "The button is clickable" implies a type and a property). Favor words and phrases over special characters.
Goal: lower the learning curve for beginners and improve readability for everyone, by using familiar, English-like constructs.
Eliminate special characters unless they serve a clear, necessary purpose. Intuitive
symbols (+ for addition) may live alongside word-based alternatives (plus) where
they are widely understood.
Goal: make the language less intimidating and more approachable by prioritizing words over symbols.
Prioritize code that is easy to read over terse or cryptic expressions. Add a paragraph to the page beats document.createElement('p').
Goal: enhance maintainability and collaboration by making code self-explanatory.
Provide user-friendly, context-aware error messages in the spirit of Elm, offering specific guidance: "Expected a number but found text — try converting it first."
Goal: let developers identify and resolve issues quickly, building productivity and confidence rather than draining them.
Enforce strict type checking, with inference where practical (store age as 25
infers a number), ensuring operations run on compatible types.
Goal: prevent runtime errors and improve reliability without sacrificing flexibility.
Incorporate advanced constructs — asynchronous operations, pattern matching — expressed naturally: "Wait for the server response, then show it."
Goal: handle genuinely complex scenarios efficiently and intuitively.
Integrate seamlessly with existing web technologies — JavaScript libraries, CSS, HTML — compiling to or interacting with them.
Goal: leverage the web ecosystem so WFL is practical and adoptable for real projects.
Embed security best practices in the language itself: automatic output escaping to prevent XSS, secure-by-default coding patterns, subprocess execution off unless deliberately enabled.
Goal: let developers — especially beginners — write secure code effortlessly, because the safe path is the default path.
Design features that are approachable and easy to learn. store name as "Alice",
not var name = 'Alice';.
Goal: remove entry barriers to programming and let novices start with confidence.
Provide powerful, concise features — pattern matching, relation definitions — that support sophisticated code without excessive verbosity.
Goal: empower seasoned developers to write advanced, efficient code for complex needs.
Stay simple to use while retaining robust capabilities for serious applications.
Goal: avoid overwhelming users with complexity, without becoming a toy.
Foster a community that values sharing, collaboration, and mutual learning through clear, understandable code — and that judges work on its merits, not on the tools used to produce it.
Goal: promote best practices and collective growth.
Optimize transparently — short-circuit evaluation, caching — without asking the developer to hand-tune.
Goal: efficient applications without manual optimization.
Provide a comprehensive standard library aligned with WFL's natural-language syntax.
Goal: offer the tools common tasks need, in the same voice as the language.
Support both small scripts and large applications through modular, maintainable structures.
Goal: let projects grow over time without rewrites or maintenance crises.
Introduce advanced concepts progressively — start with display "Hello", arrive at
async operations when ready.
Goal: a smooth journey from novice to expert, with no wall in the middle.
Make error handling and debugging straightforward, with transparent processes and clear feedback.
Goal: reduce frustration and build trust by making failure legible.
Promote standards that produce high-quality, maintainable code: clear naming, consistent structure, tests that come first.
Goal: improve quality and minimize technical debt across every project.
Challenge traditional conventions that rely on special characters or legacy practice without clear justification — mandatory semicolons among them.
Goal: align language design with natural communication and modern needs, rather than inherited habit.
- Backward compatibility is sacred. No existing WFL program breaks without a documented deprecation path.
- Tests first. Failing tests are written before the feature that satisfies them.
- Docs ship with the feature. A change to user-facing behavior is not complete until its documentation is written and its examples validated.
- AI-assisted work is welcome, and held to the same bar. WFL was built with AI. We do not discriminate against AI use; the human author remains accountable, and the quality gates are identical.
Full governance — roles, decision rights, and how to become a Contributor — lives in GOVERNANCE.md. The canonical, longer-form statement of these principles lives in Docs/wfl-foundation.md.