amcss.github.io/src/index.jade at development · amcss/amcss.github.io · GitHub

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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
header(am-HomepageHero)
  h1 AMCSS
  h2
    span Attribute Modules
    |  for CSS
main
  section(am-Example)
    :markdown
      Attribute Modules (AM) is a technique for using HTML **attributes** and their **values** rather than classes for styling elements. In doing so, each attribute effectively declares a separate namespace for encapsulating style information, resulting in more readable and maintainable HTML & CSS.

      It's not a framework or a library, it's a style that better describes the components you're building. For an introduction to how AM was developed, see the [original blog post](http://glenmaddern.com/articles/introducing-am-css) by Glen Maddern. The [specification itself](http://amcss.github.io/) is available on GitHub.

  section(am-Example)
    h3
      strong Example:
      |  Bootstrap Buttons
    :markdown
      Buttons are one of the strongest use-cases for AM. Here we've converted some of Bootstrap's button markup as an example.
    pre: code
      span(am-Code='comment')= '<!-- Large primary button -->\n'
      = '<a '
      span(am-Code='removed')= 'class="btn btn-primary btn-lg"'
      = '>Large primary button</a>\n'
      = '<a '
      span(am-Code='added')= 'am-Button="primary large"'
      = '>Large primary button</a>\n'
      span(am-Code='comment')= '\n<!-- Default button -->\n'
      = '<a '
      span(am-Code='removed')= 'class="btn btn-default"'
      = '>Default button</a>\n'
      = '<a '
      span(am-Code='added')= 'am-Button'
      = '>Default button</a>\n'
      span(am-Code='comment')= '\n<!-- Small info button -->\n'
      = '<a '
      span(am-Code='removed')= 'class="btn btn-info btn-sm"'
      = '>Small info button</a>\n'
      = '<a '
      span(am-Code='added')= 'am-Button="info small"'
      = '>Small info button</a>\n'
      span(am-Code='comment')= '\n<!-- Extra-small danger button -->\n'
      = '<a '
      span(am-Code='removed')= 'class="btn btn-danger btn-xs"'
      = '>Extra-small danger button</a>\n'
      = '<a '
      span(am-Code='added')= 'am-Button="danger extra-small"'
      = '>Extra-small danger button</a>'
    :markdown
      The original Bootstrap markup is heavily convention-based: all buttons require a `btn` class *and* a specific button class prefixed by `btn-`. It results in cluttered, repetitive markup.

      The AM version, in contrast, uses the attribute `am-Button` as an identifier, and allows straightforward, natural, additive modifiers, e.g. `large`, `primary`, etc.

    :markdown
      The CSS changes are quite straightforward:
    pre: code
      span(am-Code='removed')= '.btn'
      = ' '
      span(am-Code='added')= '[am-Button]'
      = ' { '
      span(am-Code='comment')= '/* Default button styles */'
      = ' }\n'
      span(am-Code='removed')= '.btn-primary'
      = ' '
      span(am-Code='added')= '[am-Button~="primary"]'
      = ' { '
      span(am-Code='comment')= '/* Primary colours */'
      = ' }\n'
      span(am-Code='removed')= '.btn-large'
      = ' '
      span(am-Code='added')= '[am-Button~="large"]'
      = ' { '
      span(am-Code='comment')= '/* Large sizing */'
      = ' }\n'

  section(am-Example)
    h3
      strong Example:
      |  Flexbox Grid
    :markdown
      Using a grid system is commonplace and [Flexbox Grid](http://flexboxgrid.com/) is one we're particularly fond of. Here we've converted some example markup into an AM style.

    pre: code
      = '<div '
      span(am-Code='removed')= 'class="row reverse"'
      = ' '
      span(am-Code='added')= 'am-Grid-Row="reverse"'
      = '>\n  <div '
      span(am-Code='removed')= 'class="column-12--hand column-8--lap"'
      = ' '
      span(am-Code='added')= 'am-Grid-Col="12 lap:8"'
      = '\n    <div '
      span(am-Code='removed')= 'class="box"'
      = ' '
      span(am-Code='added')= 'am-Demo="box"'
      = '>Responsive</div>'
      = '\n  </div>'
      = '\n</div>'

    :markdown
      The original markup shares some problems with all class-based grid systems. Because grid classes are used so frequently, it uses relatively *bare* css classes like `row` & `reverse`, but because columns need to be responsive, it eschews a global `col` class and instead defines <code>col-*breakpoint*-*number*</code> classes.

      The AM markup, on the other hand, defines `am-Grid-Row` and `am-Grid-Column` modules, and since each of those define a namespace we can be free to use values of our choosing. These values can make use of a wider range of characters than is convenient with classes, so we can use a <code>*breakpoint*:*number*</code> syntax, which is easier to understand at a glance. We can also adopt a mobile-first apporach by omitting the `hand` breakpoint.

  section(am-Example)
    h3
      strong Example:
      |  Traits
    :markdown
      While AM can be used as a drop-in for BEM-style class naming, you can also consider a module defining a more general *namespace* for grouping related styles. Similar to utility classes in Suit CSS, these can be thought of as reusable style **traits**, that can be applied on or within components.
    pre: code
      = '<div '
      span(am-Code='removed')= 'class="u-posAbsoluteCenter"'
      = ' '
      span(am-Code='added')= 'am-position="absolute center"'
      = '>\n  <div '
      span(am-Code='removed')= 'class="u-textTruncate u-textCenter"'
      = ' '
      span(am-Code='added')= 'am-text="truncate center"'
      = '>\n    Very centered text.\n  </div>'
      = '\n</div>'
    :markdown
      Here, we're able to make use of the fact that values for `am-position` and `am-text` operate in *different namespaces*, so we can use the value `center` in both places without worrying about naming clashes.

  section(am-Example)
    h2 Built with AM
    :markdown
      - **[am-Grid](https://github.com/benschwarz/am-grid)**<br>
        An AM grid system, inspired by Flexbox Grid. [View source](https://github.com/benschwarz/am-grid/blob/master/src/grid.css).
      - **[amcss.github.io](https://github.com/amcss/amcss.github.io/tree/development)**<br>
        A simple example of components in AM, broken up into [four simple modules](https://github.com/amcss/amcss.github.io/tree/development/src/styles/modules).

  section(am-Example)
    h2 Call for feedback
    :markdown
      We'd love to hear suggestions for inclusions to the AM specification, by adding [an issue to our tracker](https://github.com/amcss/attribute-module-specification/issues) or contributing to an existing discussion. If you create an AM-style CSS library or framework, please [let us know](https://github.com/amcss/attribute-module-specification/issues/5).

footer(am-Contributors)
  h3 Developed by
  ol
    li
      a(href='https://twitter.com/glenmaddern' target='_blank')
        img(src='/images/glen.jpg')
        | Glen Maddern
    li
      a(href='https://twitter.com/benschwarz' target='_blank')
        img(src='/images/ben.jpg')
        | Ben Schwarz
  h3 With thanks to
  ul
    li Ben Smithett
    li Florent Verschelde
    li Robbie Manson