Skip to content

Commit

Permalink
Merge pull request #199 from paperclip-ui/dev
Browse files Browse the repository at this point in the history 
Dev
  • Loading branch information
@crcn
crcn authored Dec 28, 2023
2 parents 1a9efb1 + bf26286 commit 46f29a5
Show file tree
Hide file tree
Showing 20 changed files with 242 additions and 246 deletions.
249 changes: 151 additions & 98 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,159 +8,212 @@
yarn add @paperclip-ui/cli -D && yarn paperclip designer --open
```

https://github.com/paperclip-ui/paperclip/assets/757408/429b22e0-41d6-4621-8b6e-613c1686cdda
Or download one of the standalone binaries here: https://github.com/paperclip-ui/paperclip/releases

---

- [Documentation](./docs)
<!-- - [Designer](./docs/designer.md) - Using the designer -->
- Documentation
- [Syntax](./docs/syntax.md) - Info about the DSL
- [Integration](./docs/integration.md) - Integrating Paperclip into your app
<!-- - [Configuration](./docs/config.md) - Configuring your project -->
- Examples
- [Paperclip Designer](./libs/designer/src/styles)
- [Getting Started](#getting-started)
- [CLI Usage](#cli)

---

**Paperclip is a visual programming language that offers a hybrid approach for creating web apps.** It comes with a UI builder that you can use to visually create UIs, and a readable file format that you can easily edit by hand.
Paperclip is a tiny styling language that compiles to HTML and CSS. Here's an example of what it looks like:

Paperclip aims to lower the barrier for building UIs and create an inviting user experience for everyone that wants to contribute to building web applications. It was initially designed for product teams in the hopes of bridging the gap between development teams and all other key stakeholders (designers, marketers, copywriters, PMs, etc.). With Paperclip, the hope is that other team members feel empowered to build UIs, prototype, make tweaks, giving engineers more freedom to focus on some of the harder and more mission critical parts of the application such as business logic.

**Paperclip is _not_ a replacement for hand-written code**. It's my belief that code is _not_ a problem, but incidental complexity around _tooling_ is. I.e: it's a design problem. Paperclip is an attempt to reduce some of the incidental complexity, specifically around HTML and CSS development. So, **think of Paperclip as a designer for primitive components, and a replacement for libraries like Emotion or Styled Components.**

<!-- It's also my belief that code _is_ the correct medium for writing software - even for "no-code" apps - since code is yet another "user interface" for building applications, and -->
```javascript

<!-- ### What makes Paperclip different?
// You may define individual tokens to be re-used
public token fontFamily Inter

Most other tools like Webflow are great for building websites and prototypes, and empowering everyone on your team to build in those space. Paperclip is tool to help empower everyone on your team to build the actual product.-->
public token background01 #333
public token background02 #555
public token fontColor #333

<!-- Here's how:
// You may also define groups of styles
public style defaultFont {
font-family: var(fontFamily)
color: var(fontColor)
}

- Design files are readable, and can be stored anywhere you want, including GIT.
- Everyone can work out of the same source of truth! And you'll probably want this since I'm assuming that you also have a whole quality assurance process with this (which I'm assuming you'll want if _everyone_ is touching mission critical software).
- Meaning that you can also use GIT for versioning designs and keep everything in sync (especially nice for feature development).
- Some people may also prefer _not_ to use a UI for building apps. Some people may want to use the editor, some people may want to write by hand. With Paperclip, teammates can pick medium they want for creating HTML and CSS.
- Paperclip works with you existing codebase and libraries, and can be compiled to different frameworks and languages.
-->
// re-usable chunk of HTML and CSS
public component Button {
variant hover trigger {
":hover"
}

<!--Many no-code tools are also a great _starting_ point for companies, but don't do so well as they grow bigger (hard to maintain, hard to collaborate), and you may be forced to migrate away from them as they become more complex. **Paperclip's goal is to be a solution for any size codebase, any degree of complexity, and any size team, while also catering to specific needs and preferences of everyone that may need to interact with the tool.**-->
render button {
style extends defaultFont {
background: var(background01)
}
style variant hover {
background: var(background02)
}
slot children
}
}
```

<!--### Technical features
This is a basic example, but gives you an idea of how Paperclip blends HTML and CSS into a different format. Here's what the compiled output looks like:

- Store design files anywhere you want, including GIT
- Everyone can work out of the same source of truth. And you'll probably want this since I'm assuming that you also have a whole quality assurance process for your dev stack (which I'm assuming you'll want if _everyone_ is touching mission critical software).
- Unlike other visual editors that use JSON as a file format, Paperclip files can easily be code reviewed.
- **No dependencies!** Just download the `paperclip_cli` bin from [releases](https://github.com/paperclip-ui/paperclip/releases) and start'er up. Batteries are all included.
- Paperclip works with you existing codebase and libraries, and can be compiled to different frameworks and languages.
- PC fies are compiled to strongly typed code.
- Use PC files between different platforms! E.g: use the same PC files between your Python / Rust / TypeScript apps.-->
```css
:root {
--fontFamily: Inter
--background01: #333
--background02: #333
--fontColor: #333
}

<!--- You can use any CSS framework you want within the Paperclip designer such as Tailwind, Bootstrap, or jQuery if you really want. And even Mootools. -->
.Button {
font-family: var(--fontFamily)
color: var(--fontColor)
background: var(--background01)
}

### Import Paperclip files like any other module
.Button:hover {
background: var(--background02)
}
```

Paperclip is complimentary to your existing codebase. Just use one of the built-in compilers to convert `*.pc` files in your framework or language of choice, and import them like normal code. Here's an example:
Paperclip also emits code for different libraries. Here's an example of what's emitted for React:

```typescript
import { TodoItem } from "./todo-item.pc";
<TodoItem />;
```tsx
export const Button = ({ children }) => (
<button className="Button">{children}</button>
);
```

`*.pc` are even strongly typed too in case you're working with something like TypeScript, or another strongly typed language.
In, your app code, you may use Paperclip like so:

<!--### How can I use Paperclip in my project? 🤔
```tsx
import { Button } from "./button.pc";

Paperclip is meant for styling and creating simple components. **It's probably best thought of as a design system tool**, and replaces other tools like styled components, BEM (CSS pattern), CSS modules, etc.
Paperclip works well with CSS frameworks like Tailwind since you can load these CSS frameworks into the designer and use them when you're creating your UIs visually. -->
<Button>Click me!</Button>;
```

### The DSL
### Why Paperclip?

The DSL can be thought of like a design file. It's in a DSL format because I believe
that it makes it easier for things like version control, code reviewing, and other QA stuff. That and sometimes it's just nicer to write UIs by hand.
- Provides a safe and scalable approach to styling web app.s
- Paperclip is strongly typed, and generates strongly typed code.
- There's no cascading styles in Paperclip. Instead, Paperclip uses component variants.
- No runtime. Paperclip is compiled to static HTML and CSS.
- Comes with a designer that allows you to visually edit Paperclip files.
- No dependencies! Just [download one of the standalone binaries](https://github.com/paperclip-ui/paperclip/releases).
- Super fast compiler built in Rust.

Design-wise, the DSL hopes to remove some of the gotchas around HTML and CSS (e.g: selectors, globals, style collisions) by introducing _different_ syntax for styling elements. The DSL is also a _reflection_ of an ideal user experience similar to Figma and other design tools, hoping to create an inviting and intuitive experience for people who are mostly living in those spaces.
#### Comparing CSS-in-JS

Here's an example of what a `*.pc` looks like:
Paperclip supports styled components. For example:

```javascript
public component Card {

// Variant fo the component that can be _triggered_
// by a CSS selector or media query
variant dark trigger {
".dark"
}
render div (class: class) {

// styles are added directly on the element being styled
render div {
style {
padding: 14px
font-size: 16px
font-family: sans-serif
color: black
}

// You may attach variants to any element within
// this component
style variant dark {
background: black
color: white
}
slot children
}
}
```

<!-- TODO: read more here -->
Here's the equivalent code using `styled-components`:

```typescript
import styled from "styled-components";

export const Card = styled.div`
padding: 14px;
font-size: 16px;
font-family: sans-serif;
`;
```

Paperclip compiles to static HTML and CSS, meaning that there's no runtime, which is comparable to CSS-in-JS options that use Babel transforms.

<!-- ### Why a DSL? Why not JSON?
#### Comparing with CSS

The main point of having a DSL is to have a readable file format that can be hand-written when necessary. Some other points:
Paperclip is different than CSS in that Paperclip doesn't support the cascading part (which means that you don't risk style collisions). Instead, you have variants. For example, in CSS you might write:

- Code reviewing is easier with a DSL
- quality assurance - easier to see how well a document is structured
- You _want_ this since HTML and CSS has behavior around responsiveness and such. It's not like you can just look at a UI and QA it based on that - you need to inspect the document.
- Sometimes it's just faster to type out the UI by hand rather than feeling restricted by a visual editor. This was a big one for me.
```css
.Page {
font-size: 14px;
}
@media screen and (max-width: 700px) {
.Page {
font-size: 21px;
}
}
```

In Paperclip, the equivalent would be:

An earlier version of Paperclip _did_ use JSON and it failed the practicality test _I think_. If you want to get a sense about how impractical JSON felt, take a look at this file: https://github.com/crcn/tandem-old/blob/10.0.0/packages/front-end/src/components/root/workspace/right-gutter/styles/pretty/panes/box-shadows.pc-->
```typescript
trigger mobileTrigger "@media screen and (max-width: 700px)"

public component Page {
variant mobile trigger {
mobileTrigger
}
render div {
style {
font-size: 14px
}
style variant mobile {
font-size: 21px
}
slot children
}
}
```

<!-- ### History 📚
Paperclip is also strongly typed. For example:

This version of Paperclip is the result of many years of work and experimentation in the no-code space and working at Webflow. Here are some prior versions of Paperclip -->
```typescript
style defaultFont {

### Should I use Paperclip right now?
// Error!
font-family: var(fontFamily)
}
```

Are you working on an experiment or side-project? Sure! Give it a whirl! I'd love to hear what you think. All feedback is welcome! Though, I _wouldn't_ recommend using Paperclip right now for mission critial pieces of software since it's still very alpha, and very buggy.
Would emit an error since `fontFamily` doesn't exist.

<!-- ### Just covers the UI
Lastly, Paperclip files aren't limited to CSS, and are designed to compile to different targets (more of this in the future).

## Design and code in parallel!
### Getting Started

Paperclip is just a replacement for HTML and CSS, and nothing more. -->
1. **[download one of the releases](https://github.com/paperclip-ui/paperclip/releases), or run `yarn install @paperclip-ui/cli -D`**

<!-- ### Simplified and safe data model
2. **run this command in your project directory:**

HTML and CSS can feel complex and daunting to some people, and there are also many gotchas around web development that people. Paperclip -->
```
paperclip init
```

<!-- ### Can handle the most complex web apps
This will create a `paperclip.config.json` file for you.

Paperclip is designed to take on any problem that you throw at it -->
3. **Copy the following contents to `src/hello.pc`**

<!-- ### Invite everyone on your team build UIs 👨🏻‍🎨
```typescript
public component Hello {
render div {
style {
color: red
}
slot children
}
}
```

No more needing to ask developers to make HTML and CSS changes, Paperclip enables anyone to make changes themselves using the UI builder. Marketers, designers, copywriters, whoever. Invite everyone to build UIs, and ship things faster than ever!
4. **Run `paperclip build`**

- spot edit visual bugs
This will compile your `*.pc` files into code that you can import
directly into your app.

-->
And that's it! 🎉

## Roadmap
<!--## Designer
- More design tooling
- canvas tooling
- potentially custom components
- bringing UX closer to Figma for a more inviting user experience
- Online designer
- multi-player editing too!
- AI assistance
- Figma integration
- ability to copy + paste designs to Paperclip
- ability to keep designs in sync
https://github.com/paperclip-ui/paperclip/assets/757408/429b22e0-41d6-4621-8b6e-613c1686cdda-->
Loading

0 comments on commit 46f29a5

Please sign in to comment.