-
Notifications
You must be signed in to change notification settings - Fork 18
/
documentation.html
127 lines (92 loc) · 5.78 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
---
layout: base
title: Documentation
---
<div class="cl-docs">
<div class="page-title-bar">
<div class="inner-content">
<h2>Clank Documentation</h2>
</div>
</div>
<div id="docs">
<div id="docs-nav">
<h4>General</h4>
<ul class="nav nav-tabs nav-stacked">
<li><a href="#what-is">What is Clank?</a></li>
<li><a href="#why">Why Clank?</a></li>
<li><a href="#skinning-mechanism">Skinning mechanism</a></li>
<li><a href="#support">Browser support</a></li>
<li><a href="#scss-conventions">(S)CSS conventions</a></li>
<li><a href="#component-includes">Component includes</a></li>
<li><a href="#generators">Generators</a></li>
</ul>
</div>
<div id="content">
<article>
<h3 id="what-is">What is Clank?</h3>
<p>Clank is an open source prototyping framework for mobile apps. Think of it as Twitter Bootstrap but for prototyping native apps.</p>
<hr>
<h3 id="why">Why Clank?</h3>
<h4>Actually looks like a native app</h4>
<p>We strive to actually look like a native app (as far as web tech allows us to go) instead of pseudo implementations.</p>
<h4>Component based: pick and choose</h4>
<p>Clank is a collection of HTML/CSS components. For example, a button is a component. It has it's own SCSS file: <code>components/_button.scss</a></code>.</p>
<p>Every component stands on its own and can't influence other components. Clank has <a href="#scss-conventions">strong rules</a> on component naming to avoid any style clashes.</p>
<p>A good component only defines layout and provide hooks for specific looks.</p>
<h4></h4>
<p>We strive to actually look like a native app (as far as web tech allows us to go) instead of pseudo implementations.</p>
<hr>
<h3 id="skinning-mechanism">Skinning-mechanism</h3>
<p>Clank uses variables in SCSS to provide an easy way to easily change the look of Clank-made applications.</p>
<p>Changing the global color of headers, bars and buttons is as easy as changing one variable:</p>
{% highlight scss %}$accent-color: red{% endhighlight %}
<h4>Variables for cross platform design</h4>
<p>Every operating system has its own look and feel. Clank acknowledges that you are building apps for multiple platforms. We see each part of the design as a variable that can be altered:</p>
{% highlight scss %}
$functional-shadows: true
$decorational-shadows: false
{% endhighlight %}
<p>Sometimes in more detail:</p>
{% highlight scss %}$border-radius: 4px;{% endhighlight %}
<p>This way, it's easy to generate an iOS or Android specific style sheet by switching out the variables. Or maybe you want to create a unified look that looks like your brand instead of chasing platform guidelines. It's all possible.</p>
<p>You also want to switch on a functional level i.e. you might want to swap out an iOS header for an Android action bar component. More on this in <a href="#component-includes">component includes</a>.</p>
<h4>Philosophy</h4>
<p>You should try to make your application using standard components. The standard components used in iOS and Android have a lot of work behind them. Face it, you don't have 2 weeks to perfect a <code><select></code>.</p>
<hr>
<h3 id="component-includes">Component includes</h3>
<p><em>Component includes is a planned feature where you can swap components in your prototypes depending on the operating system. E.g. for your Android application you might want to use Android style tabs, but the same functionality in the iOS version uses a segmented control.</em></p>
<hr>
<h3 id="browser-support">Browser support</h3>
<p>It's not advisable to use Clank for production work since it only supports new and modern browsers like <em>Google Chrome</em>. A lot of the techniques used in Clank depend on newer CSS properties such as Flexbox. For now, Clank is a prototyping tool and testbed for modern web technologies.</p>
<hr />
<h3 id="scss-conventions">(S)CSS conventions</h3>
<p>We use SCSS for all CSS because it provides us with a way to extend CSS with variables and mixins.</p>
<p>Every component should be prefixed with <code>cl-</code>:</p>
{% highlight scss %}.cl-accordion { }{% endhighlight %}
<p>This is verbose but the only way to not clash with other libraries until Web Components are commonplace.</p>
<p>A child element dependent on the component should be added with a hyphen:</p>
{% highlight scss %}.cl-accordion-item { }{% endhighlight %}
<p>State should be added with a double underscore:</p>
{% highlight scss %}.cl-accordion-item__disabled { }{% endhighlight %}
<p>This prevents too many nested selectors in SCSS.</p>
<p>This naming technique has been coined <a href="http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/">BEM</a>.</p>
<hr />
<h3 id="generators">Generators</h3>
<p><em>Note that generators are a work in progress and they do not exist yet</em>.</p>
<h4>What is a generator?</h4>
<p>A generator is simply a bash script that generates code for you. This makes it easy to, for example, add new screens or components to your project.</p>
<h4>Available generators</h4>
<ul class="bordered-list">
<li>
<p><strong>generate-page.sh</strong></p>
<p>Creates a new page.</p>
</li>
<li>
<p><strong>generate-component.sh</strong></p>
<p>Creates a new component.</p>
</li>
</ul>
</article>
</div>
</div>
</div>